Skip to content
InfraKitchen
Esc
↑↓navigate↵open⌘Jpreview
On this page

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_key is the template’s unique key
  • resource_name_slug is 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
    • aws_eks/
      • prod_eks_cluster/
        • main.tf
        • variables.tf
        • outputs.tf
        • terraform.tfvars.json
        • backend.tfvars
        • Makefile

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_progress at start of a sync/approve/reject/destroy pipeline
  • Set to done on completion
  • Set to error on 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:

  1. Clones the repository (SSH or HTTPS depending on integration type)
  2. Creates a new branch from the default branch
  3. Copies or deletes the resource code path
  4. Commits with a structured message including the initiating user
  5. Force-pushes the branch so it always reflects the latest state
  6. Creates a PR, skipping if one already exists for the head branch
  7. 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

Last updated on