> For the complete documentation index, see [llms.txt](https://docs.terrakube.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.terrakube.io/2.34.0/run-terraform/workspaces/creating-workspaces.md).

# Creating Workspaces

{% hint style="info" %}
**Manage Workspaces** permission is required to perform this action, please check [Team Management](/2.34.0/set-up/organizations/team-management.md) 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](/2.34.0/api-reference/getting-started.md).

<figure><img src="https://1229094460-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTN6M529qVFnas8hChf2y%2Fuploads%2Fgit-blob-3e8e7765c09a6f68e7af76c6339223915ae5cb11%2Fworkspace-new-wizard.png?alt=media" alt="The New Workspace wizard"><figcaption><p>The New Workspace wizard</p></figcaption></figure>

### Version Control workflow

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

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

Choose the **Version control workflow**

Select an existing version control provider or click **Connect to a different VCS** to configure a new one. See [VCS Providers](/2.34.0/set-up/vcs-providers.md) for more details.

For GitHub (OAuth or App), GitLab, Bitbucket, and Azure DevOps connections, search and pick a repository from a paginated list backed by the provider's API instead of typing a URL — this scales to organizations with thousands of repositories. Select one and click **Continue**.

{% hint style="info" %}
SSH connections don't support repository discovery, since there's no provider API to query — provide the git repository URL directly, in SSH format. Example <git@github.com>:jcanizalez/terraform-sample-repository.git. For more information see [SSH](/2.34.0/set-up/vcs-providers/ssh.md)
{% endhint %}

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, or a version constraint (`~> 1.5`, `^1.5.0`, `1.5.x`, `>= 1.5, < 2.0`, etc.) to resolve to the latest matching version instead of pinning an exact one. Check [Custom Terraform CLI Builds](/2.34.0/getting-started/deployment/custom-terraform-cli-builds.md) 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://1229094460-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTN6M529qVFnas8hChf2y%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.

You will be redirected to the Workspace page

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

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. See [Webhooks](/2.34.0/run-terraform/workspaces/webhooks.md) for how to configure additional events (pull requests, releases) and the PR comment workflow.

### CLI-driven Workflow

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

Choose the **CLI-driven workflow**

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](/2.34.0/getting-started/deployment/custom-terraform-cli-builds.md) if you want to restrict the versions in your Terrakube instance. |

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

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](/2.34.0/run-terraform/workspaces/cli-driven-workflow.md)
{% endhint %}

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

### API-driven Workflow

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

Choose the **API-driven workflow**

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](/2.34.0/getting-started/deployment/custom-terraform-cli-builds.md) if you want to restrict the versions in your Terrakube instance. |

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

ou will be redirected to the Workspace page.

{% hint style="info" %}
For more details how to use the Terrakube API. See [API-driven Workflow](/2.34.0/run-terraform/workspaces/api-driven-workflow.md)
{% endhint %}

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

### Changing the repository or VCS provider

Under **Settings → General**, a Version Control workspace can be pointed at a different **VCS provider** or **Repository URL**, for example after moving from GitHub to GitLab. State, variables and run history are kept. If the workspace has a [webhook](/2.34.0/run-terraform/workspaces/webhooks.md), Terrakube asks you to confirm and removes it first; enable it again afterwards. The repository field is not shown for CLI-driven workspaces.

<figure><img src="https://1229094460-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTN6M529qVFnas8hChf2y%2Fuploads%2Fgit-blob-ee3651ea56b6c819f32b5db5fc5e46d2a5c204f6%2Fworkspace-settings-general.png?alt=media" alt="Settings, General"><figcaption><p>Settings, General</p></figcaption></figure>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.terrakube.io/2.34.0/run-terraform/workspaces/creating-workspaces.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.