Workspace
Workspaces connect your managed infrastructure to Git: for every Resource, InfraKitchen commits the OpenTofu/Terraform code it generates into the workspace’s repository and opens a pull request, so every change is version-controlled and reviewed before it reaches your default branch. Where Templates define structure and Resources are concrete instances, the Workspace is where their code becomes visible and reviewable.
A workspace is a single repository on a supported Git provider (GitHub, Bitbucket, Azure DevOps). You create the repository in your provider first, then register it in InfraKitchen — InfraKitchen never creates repositories.
How It Works
When a Resource is provisioned, updated, or destroyed, InfraKitchen records the change in the workspace repository: it commits the resource’s generated code to a branch and opens a pull request for you to approve or reject.
InfraKitchen handles all of the Git work:
- Cloning the repository and creating a branch from the default branch
- Copying the generated OpenTofu/Terraform code into the resource’s directory — or removing that directory when the resource is destroyed (see Repository Layout)
- Opening a pull request for the change
- Merging the pull request when the change is approved, closing it when rejected
Every operation is recorded in the audit log and can trigger notifications for subscribed users.
Repository Layout
Each Resource gets its own directory at the top level of the workspace repository, placed at <template_key>/<resource_name_slug>/, where:
template_keyis the template’s unique keyresource_name_slugis the lowercased resource name with spaces replaced by underscores
With multiple Resources, the repository looks like:
- workspace-repo/
- aws_vpc/
- prod_network_vpc/
- main.tf
- variables.tf
- outputs.tf
- terraform.tfvars.json
- backend.tfvars
- Makefile
- prod_network_vpc/
- aws_eks/
- prod_eks_cluster/
- main.tf
- variables.tf
- outputs.tf
- terraform.tfvars.json
- backend.tfvars
- Makefile
- prod_eks_cluster/
- aws_vpc/
Each directory contains two kinds of files — the module code the Resource was created from, and files InfraKitchen generates for it:
| File | Purpose |
|---|---|
*.tf module files |
The module code — from the Code Repository — that the Resource was created from |
terraform.tfvars.json |
Resolved values for all variables, including values inherited from parent resources, project defaults, and tags |
backend.tfvars |
Remote state backend configuration pointing at the resource’s Storage |
Makefile |
Shortcuts for tofu init, plan, apply, and destroy |
Lifecycle & Actions
| Action | Trigger | Effect | Git Operation |
|---|---|---|---|
| Create | Workspace registration | Stores metadata only | None |
| Sync (Provision / Update) | Resource provision/update | Copies resource code into repo path on a new branch | Clone, new branch, copy, commit, push, PR create |
| Delete (Destroy) | Resource destroy | Removes resource code directory via new branch | Clone, new branch, delete directory, commit, push, PR create |
| Approve | Manual approval of resource changes | Merges the pending PR into default branch | API merge PR |
| Reject | Manual rejection | Closes the pending PR without merge | API close PR |
| Recreate | Forced re-sync (internal) | Sync + approve flow | Combined |
| Destroy Workspace | Admin deletion (only if no dependencies) | Removes workspace record | None |
Workspace status transitions revolve around task execution:
- Set to
in_progressat start of a sync/approve/reject/destroy pipeline - Set to
doneon completion - Set to
erroron failure or retry exhaustion
Branch Naming Convention
Branches created for resource operations follow:
| Resource State | Branch Prefix | Example |
|---|---|---|
| Provision / Provisioned | update_ |
update_prod_network_vpc |
| Destroy / Destroyed | delete_ |
delete_prod_network_vpc |
The suffix derives from the slugified resource name.
Pull Request Flow
For each resource provision/update/destroy that targets a workspace, InfraKitchen:
- Clones the repository (SSH or HTTPS depending on integration type)
- Creates a new branch from the default branch
- Copies or deletes the resource code path
- Commits with a structured message including the initiating user
- Force-pushes the branch so it always reflects the latest state
- Creates a PR, skipping if one already exists for the head branch
- Waits for a manual action: Approve (merge PR into default branch) or Reject (close PR without merge)
Workspace Properties
A workspace has the following properties:
| Property | Description | Notes |
|---|---|---|
| Name | Derived from provider metadata (GitHub repo name, Bitbucket slug, Azure DevOps repo name) | Immutable after creation |
| Workspace Provider | Git service backing the workspace | github, bitbucket, azure_devops |
| Integration | The configured integration object used for auth & API access | Must match provider |
| Description | Human-readable notes about the workspace | Editable |
| Labels | Tags for organization & filtering | Free-form list |
| Status | Internal processing state | in_progress, done, error |
| Configuration.name | Repository name | Mirrors provider value |
| Configuration.url | Canonical HTML/portal URL | Provider dependent |
| Configuration.ssh_url | SSH clone URL | Used if integration uses SSH |
| Configuration.https_url | HTTPS clone URL (username stripped) | Used if integration uses HTTPS |
| Configuration.default_branch | Branch used as merge base | Usually main (GitHub/Azure) or provider default |
| Configuration.organization | Owning organization / project key | Provider-specific mapping |
| Created At / Updated At | Timestamps | Auto-managed |
| Creator | User who registered workspace | For audit & permissions |
Creating a Workspace
You must first create a repository in your Git provider (GitHub, Bitbucket, Azure DevOps). Then register that repository in InfraKitchen.
Navigate to Workspaces
Go to Workspaces in the sidebar and click Create.
Select provider and integration
Select the Git provider and the integration to authenticate with, then choose the repository — InfraKitchen fetches its details via the provider API.
Save
Optionally add a description and labels, then save.
InfraKitchen stores the provider-specific details in a unified configuration object.
Updating a Workspace
Only the description and labels can be changed; name, provider, integration, and configuration fields are immutable. Every update is recorded in the audit log.
Deleting a Workspace
A workspace can be deleted only if it has no dependent resources.
Constraints:
- No resources referencing the workspace
- No pending or in-progress tasks
Attempting deletion with dependencies raises an error.
Permissions
| Action | Permission | Notes |
|---|---|---|
| View | Authenticated users | Basic list & detail |
| Create | Workspace create permission | Integration must be accessible |
| Update | Write/admin on workspace | Limited fields |
| Approve / Reject | Write/admin on resource & workspace | Acts on existing PR |
| Delete Workspace | Admin on workspace | Requires no dependencies |
Access is enforced through the platform’s RBAC and entity-level permissions.
Integration with Other Features
- Storage — OpenTofu/Terraform state stays in Storage; the workspace repository contains generated code only.
- Pull requests — the human approval gate before code lands in the default branch, enabling policy checks or external CI.
Troubleshooting
| Symptom | Possible Cause | Resolution |
|---|---|---|
| PR not created | Existing branch/PR already open | Approve or close existing PR; trigger resync |
Workspace status stuck in_progress |
Task failure before final state | Check entity logs; look for Git auth errors |
| Missing resource directory | Sync not triggered or branch not merged | Verify resource state and PR approval |
| Merge fails | API permissions insufficient | Ensure integration token has repo write & PR merge rights |