# Workspaces
## Introduction
Workspaces are Gomboc's core organizing concept for managing, scanning, and remediating Infrastructure as Code (IaC) across connected source code repositories. Designed for a seamless developer experience, a Workspace is uniquely defined by:
* IaC Tool (e.g., Terraform, CloudFormation)
* Repository (e.g., GitHub, GitLab, Bitbucket, Azure Repos)
* Branch (default or protected)
* Path (directory containing the IaC module)
Once created, a Workspace becomes the control plane for tracking posture, running scans, applying rules, and managing remediations, all directly from the Gomboc UI or integrated into your CI pipelines.
#### What Is a Workspace?
Think of a Workspace as a mirror of a deployable unit of IaC in your version control system. Gomboc Workspaces:
* Are created automatically based on connected repositories and supported IaC detections
* Track changes, findings, and fixes over time
* Power Gomboc’s PR scanning and drift remediation workflows
Each Workspace is based on a canonical scenario (repo + branch + path + IaC tool), and only default and protected branches are considered for workspace creation.
***
## Discovery & Indexing
When you connect your SCM provider to Gomboc:
1. Gomboc scans your repos to detect repositories possibly containing IaC
2. The repository is scanned and Workspaces are created based on the detected contents the repository
3. Your PRs are mapped to ancestor Workspaces by tracing to the nearest default/protected branch
4. An initial scan is run to establish a baseline and detect misconfigurations
5. Gomboc PR-ready fixes are generated per Workspace
### Example
* **Repo:** `infra-network`
* **Branches:** `main` (default), `prod` (protected)
* **Paths:** `/vpc`, `/eks`
**Workspaces created**
* `infra-network-main-vpc`
* `infra-network-main-eks`
* `infra-network-prod-vpc`
* `infra-network-prod-eks`
### Workspace Discovery
New Workspaces are discovered under the following conditions:
1. A new SCM integration is created, resulting in a workflow discovery of workspaces is triggered
2. On a scheduled basis (hourly by default), repositories are indexed for new workspaces.
**Special Cases**
If IaC code is submitted to be merged on a new path under a default branch (which would mean it is a new workspace), then it will scanned as part of the change request review but that scan will not be visible in the portal UI under a workspace yet because it has yet to be created. The workspace will be added to the portal UI once the scheduled indexing for workspaces occurs. If needed, you can follow the manual workspace creation process in the interim.
***
## Workspace Creation and Editing
Users can create workspaces manually by selecting the “Add Workspace” button in the portal interface and completing the details in the creation dialogue.
You can create a Workspace from **Workspaces → Add Workspace** by providing:
* **IaC tool** – Terraform / CloudFormation / (others as supported)
* **SCM integration** – the account/org/group to search under
* **Repository** – code repo containing the module
* **Branch** – default or protected branch to anchor the Workspace
* **Path** – folder containing the IaC module
### **Editing a workspace name**
* Go to Workspaces and use Search/Filters to open the workspace you need.
* Click the edit icon next to the workspace name to change it.
***
## Scan Triggers & Modes
How scans run for a Workspace and the difference between Audit vs PR Mode.
### How scans are triggered
* **On demand (Portal):** From a Workspace, click **Run scan** to start an immediate analysis.
* **Pull requests (CI):** On PR open/update, Gomboc identifies the **ancestor Workspace** (via branch ancestry + path), runs a scan, and posts results to the PR (checks and/or comments).
### Modes per Workspace
Each Workspace operates in one of two modes:
| Mode | Behavior |
| ----------------- | ------------------------------------------------------------------------------------------------ |
| **Audit only** | Reports findings and suggested fixes. No PR is created automatically. |
| **Deliver fixes** | Opens a side PR with automated fixes (similar to Dependabot). Developers review, edit, or merge. |
***
## FAQ
#### Common Workspaces questions:
Can I delete a Workspace?
Workspaces can’t be permanently deleted. Archive them instead, then filter to hide archived items.
Can I manually create a Workspace?
Yes. From **Workspaces → Add Workspace**, provide **IaC tool**, **SCM integration**, **Repository**, **Branch** (default/protected), and **Path**. Gomboc validates the path and starts a baseline scan.
Are IDE scans linked to Workspaces?
**No. IDE scans are local and not linked to Workspaces.** If your project has a `.git` folder, we may suggest a related Workspace, but IDE findings aren’t added to Workspace posture or PR checks. When you open/update a PR, those changes are scanned against the ancestor Workspace.
Why doesn’t Gomboc create Workspaces for feature branches?
To avoid noise. PR scans map to the ancestor Workspace on a default/protected branch. This keeps the inventory clean and focused on deployable IaC.
***
\
Need help? Contact us at \\
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.gomboc.ai/workspaces.md?ask=
```
The question should be specific, self-contained, and written in natural language.
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.