# Creating Workspaces

{% hint style="info" %}
**Manage Workspaces** permission is required to perform this action, please check [team-management](https://docs.terrakube.io/user-guide/organizations/team-management "mention") for more info.
{% endhint %}

When creating a Workspace, Terrakube supports 3 workflows types and based on the selected workflow you will need to provide some parameters. Please refer to each workflow section for more reference.

* [Version Control workflow](#version-control-workflow): Store your Terraform configuration in a git repository, and trigger runs based on pull requests and merges.
* [CLI-driven workflow](#cli-driven-workflow): Trigger remote Terraform runs from your local command line.
* [API-driven workflow](#api-driven-workflow): A more advanced option. Integrate Terraform into a larger pipeline using the [Terrakube API](https://docs.terrakube.io/api/getting-started).

### Version Control workflow

Click **Workspaces** in the main menu and then click the **New workspace** button

<figure><img src="https://4014930676-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MfAN3V983Y82_trlbcu%2Fuploads%2Fgit-blob-35fd51f0856ae21e21f808b786ef0950a8547e47%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

Select the IaC type for now we support terraform and open tofu

<figure><img src="https://4014930676-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MfAN3V983Y82_trlbcu%2Fuploads%2Fgit-blob-571e6de1b1ef501b440b721bc598754618630fd9%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

Choose the **Version control workflow**

<figure><img src="https://4014930676-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MfAN3V983Y82_trlbcu%2Fuploads%2Fgit-blob-42d7e27733e287c579e5734caec8d553969a898f%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

Select an existing version control provider or click **Connect to a different VCS** to configure a new one. See [vcs-providers](https://docs.terrakube.io/user-guide/vcs-providers "mention") for more details.

<figure><img src="https://4014930676-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MfAN3V983Y82_trlbcu%2Fuploads%2Fgit-blob-a0dbcc3ba75bc341f464d984360ce3e795b6a6d2%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

Provide the git repository URL and click the **Continue** button.

{% hint style="info" %}
If you want to connect to a private git repo using SSH Keys you will need to provide the url in ssh format. Example <git@github.com>:jcanizalez/terraform-sample-repository.git. For more information see [ssh](https://docs.terrakube.io/user-guide/vcs-providers/ssh "mention")
{% endhint %}

<figure><img src="https://4014930676-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MfAN3V983Y82_trlbcu%2Fuploads%2Fgit-blob-178ccdde11741667b5d8dcbc67f333bed2c38748%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

Configure the workspace settings.

| Field                       | Description                                                                                                                                                                                                                                          |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Workspace Name              | The name of your workspace is unique and used in tools, routing, and UI. Dashes, underscores, and alphanumeric characters are permitted.                                                                                                             |
| VCS branch                  | A list of branches separated by comma that jobs are allowed to kicked off from VCS webhook. This is not used for CLI workflow.                                                                                                                       |
| Terraform Working Directory | Default workspace directory. Use / for the root folder                                                                                                                                                                                               |
| Terraform Version           | The version of Terraform to use for this workspace. Check [custom-terraform-cli-builds](https://docs.terrakube.io/getting-started/deployment/custom-terraform-cli-builds "mention") if you want to restrict the versions in your Terrakube instance. |

Once you fill the settings click the **Create Workspace** button.

<figure><img src="https://4014930676-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MfAN3V983Y82_trlbcu%2Fuploads%2Fgit-blob-61120811d8713a6859be29ae2bf57bcd18659b47%2Fworkspace-settings-vcs.png?alt=media" alt=""><figcaption></figcaption></figure>

When using a VCS workflow you can select which branches, folder and action (aka, Default template (VCS push)) the runs will be triggered from when a git push action happens.

The `VCS branches` accepts a list of branches separated by comma, the first in the list is used as the default for the runs kicked off from UI. The branches are compared as prefixes against the branch included in the payload sent from VCS provider.

<figure><img src="https://4014930676-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MfAN3V983Y82_trlbcu%2Fuploads%2Fgit-blob-df3cc392fbb60c1494cfe8f5d3c4e857e9585981%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

You will be redirected to the Workspace page

<figure><img src="https://4014930676-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MfAN3V983Y82_trlbcu%2Fuploads%2Fgit-blob-a6cb95bc61dafa716e894452491c62859b357437%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

And if you navigate to the **Workspace** menu, you will see the workspace in the Workspaces list

<figure><img src="https://4014930676-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MfAN3V983Y82_trlbcu%2Fuploads%2Fgit-blob-f7a93798430163a3fdd73d0bb9c784baf297adaf%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

Once you create your workspace, Terrakube sets up a webhook with your VCS. This webhook runs a job based on the selected template every time you push new changes to the set workspace branches. However, this feature does not work yet with Azure DevOps VCS provider.

### CLI-driven Workflow

Click **Workspaces** in the main menu and then click the **New workspace** button

<figure><img src="https://4014930676-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MfAN3V983Y82_trlbcu%2Fuploads%2Fgit-blob-843d1b72f699dad2b6e95f1ec44421f10efc5652%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

Choose the **CLI-driven workflow**

<figure><img src="https://4014930676-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MfAN3V983Y82_trlbcu%2Fuploads%2Fgit-blob-5ee4f74b33505b987021cc90a0185f658c33d222%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

Configure the workspace settings.

| Field             | Description                                                                                                                                                                                                                                          |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Workspace Name    | The name of your workspace is unique and used in tools, routing, and UI. Dashes, underscores, and alphanumeric characters are permitted.                                                                                                             |
| Terraform Version | The version of Terraform to use for this workspace. Check [custom-terraform-cli-builds](https://docs.terrakube.io/getting-started/deployment/custom-terraform-cli-builds "mention") if you want to restrict the versions in your Terrakube instance. |

Once you fill the settings click the **Create Workspace** button.

<figure><img src="https://4014930676-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MfAN3V983Y82_trlbcu%2Fuploads%2Fgit-blob-7eb518acfd3658332842b8d0b78dabc7f7f6cfaf%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

You will be redirected to the Workspace page.

{% hint style="info" %}
The overview page for CLI-driven workspaces show the step to connect to the workspace using the Terraform CLI. For more details see [cli-driven-workflow](https://docs.terrakube.io/user-guide/workspaces/cli-driven-workflow "mention")
{% endhint %}

<figure><img src="https://4014930676-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MfAN3V983Y82_trlbcu%2Fuploads%2Fgit-blob-4e735787a66e05df7ece7e46198c78cb9018474f%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

And if you navigate to the **Workspace** menu you will see the workspace in the Workspaces list

<figure><img src="https://4014930676-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MfAN3V983Y82_trlbcu%2Fuploads%2Fgit-blob-9d011a741ed01ab103e63f47b9bb85c4c67c2373%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

### API-driven Workflow

Click **Workspaces** in the main menu and then click the **New workspace** button

<figure><img src="https://4014930676-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MfAN3V983Y82_trlbcu%2Fuploads%2Fgit-blob-35fd51f0856ae21e21f808b786ef0950a8547e47%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

Choose the **API-driven workflow**

<figure><img src="https://4014930676-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MfAN3V983Y82_trlbcu%2Fuploads%2Fgit-blob-e86bd23d6eae3729c7ce383a0a159e8fe143ab93%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

Configure the workspace settings.

| Field             | Description                                                                                                                                                                                                                                          |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Workspace Name    | The name of your workspace is unique and used in tools, routing, and UI. Dashes, underscores, and alphanumeric characters are permitted.                                                                                                             |
| Terraform Version | The version of Terraform to use for this workspace. Check [custom-terraform-cli-builds](https://docs.terrakube.io/getting-started/deployment/custom-terraform-cli-builds "mention") if you want to restrict the versions in your Terrakube instance. |

Once you fill the settings click the **Create Workspace** button.

<figure><img src="https://4014930676-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MfAN3V983Y82_trlbcu%2Fuploads%2Fgit-blob-487253660ac11fa8ba7ab352eb601fd9ca6510a4%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

ou will be redirected to the Workspace page.

{% hint style="info" %}
For more details how to use the Terrakube API. See [api-driven-workflow](https://docs.terrakube.io/user-guide/workspaces/api-driven-workflow "mention")
{% endhint %}

<figure><img src="https://4014930676-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MfAN3V983Y82_trlbcu%2Fuploads%2Fgit-blob-17cb00a66c7871d03e3b46f4a9b2f08e799ee492%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

And if you navigate to the **Workspace** menu you will see the workspace in the Workspaces list

<figure><img src="https://4014930676-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MfAN3V983Y82_trlbcu%2Fuploads%2Fgit-blob-78030eaa5754d13aeeb60135fef7dc367d7385b1%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>