Configure Workspaces
Workspaces help organize your infrastructure repositories. Learn how to find and configure your Atmos Pro workspace ID.
Workspaces are the top-level organization for your Atmos Pro account. A workspace is your account in Atmos Pro. It is a collection of GitHub repositories managed by a team, and represents everything your team owns and operates within Atmos Pro. Workspaces group your team members and connected repositories, providing a boundary for collaboration and management.
Not Terraform Workspaces
Atmos Pro workspaces are not related to Terraform
workspaces. An Atmos Pro workspace is your
team's account — a collection of GitHub repositories, team members, and settings. Terraform workspaces, by contrast,
are a state management concept for isolating state files within a single configuration.
To create a workspace, you need to be an administrator of the Atmos Pro account.
Each workspace is uniquely identified by a value called it's
Workspace ID.This ID is not sensitive and is used as part of GitHub OIDC exchange to authenticate workflows with the correct workspace.
Since a single repository can be associated with multiple workspaces, setting this ID tells Atmos which workspace to use. This ensures your infrastructure changes are deployed to the correct environment and that workflows are securely scoped to the right workspace context.
The workspace ID looks something like
ws_xxxxxxxxxxxxxxxxxxxxxxxxxxxx.To find your workspace ID:
- 1Log in to your Atmos Pro app at Atmos Pro dashboard
- 2Click on the "Workspace Settings" (gear icon) in the bottom left corner
- 3Your workspace ID will be displayed under "Workspace Settings"
Once you have your workspace ID, set it on your GitHub repository (or organization, or environment) as an Actions variable named
ATMOS_PRO_WORKSPACE_ID. The fastest way is the GitHub CLI — use the UI if you prefer click-through configuration.Run
gh variable set from a checkout of the repo (or from anywhere with --repo). When you're signed in, the snippets below have your real workspace ID baked in — just copy and run.Repository scope (most common):
gh variable set ATMOS_PRO_WORKSPACE_ID --body "ws_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"Organization scope — share one workspace ID across every repo in the org:
gh variable set ATMOS_PRO_WORKSPACE_ID --org my-org --visibility all --body "ws_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"Environment scope — scope per GitHub Environment (e.g.,
prod, staging):gh variable set ATMOS_PRO_WORKSPACE_ID --env prod --body "ws_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"Verify it landed:
# Repository scope
gh variable get ATMOS_PRO_WORKSPACE_ID
# Organization scope
gh variable get ATMOS_PRO_WORKSPACE_ID --org my-org
# Environment scope
gh variable get ATMOS_PRO_WORKSPACE_ID --env prodWorkspace ID is not sensitive
The workspace ID is used as part of GitHub OIDC exchange to authenticate workflows with the correct workspace. Store
it as an Actions variable (not a secret) so it remains visible in logs and reproducible across environments.
After configuring your workspace ID, you need to add your GitHub repositories to your Atmos Pro workspace. This process connects your repositories to Atmos Pro so they can be managed and deployed through the platform.
You can add repositories to your workspace through the Atmos Pro dashboard:
- 1Navigate to Import Repositories: Go to Import Repositories and log in to your account
- 2Select Organization: Choose your GitHub organization from the dropdown menu
- 3Search and Select: Use the search field to find specific repositories, or browse through the list
- 4Import Repository: Click the "Import" button next to each repository you want to add to your workspace
The repositories you can import depend on:
- GitHub App Installation Scope: Only repositories accessible to your GitHub App installation will appear
- User Permissions: You must have appropriate permissions in the GitHub organization to see and manage repositories
- Repository Visibility: Both public and private repositories can be imported (subject to GitHub App permissions)
Repository Permissions
After importing a repository, you'll need to configure repository permissions to enable workflow dispatches. See the
next section for details on setting up permissions.
Repository permissions control which branches are allowed to dispatch specific workflows in response to GitHub events.
To use Atmos Pro with your repository, you need to configure the
How it works
Affected Stacks Create permission. This permission is required for the OIDC token exchange between your GitHub Actions workflows and the Atmos Pro API.To configure the required permission:
- 1Go to the Atmos Pro dashboard
- 2Navigate to the "Configured Repositories" menu
- 3Find your repository in the list
- 4Click the settings icon (gear) next to your repository
- 5Switch to the Permissions tab in the settings panel
- 6Click "Add Permission"
- 7In the form:
- Select "Affected Stacks Create" from the permission dropdown menu
- For "Workflow", you can either:
- Leave as wildcard (
*) to allow all workflows - Specify specific workflow names (e.g.,
atmos-terraform-plan.yaml,atmos-terraform-apply.yaml)
- For "Branch", you can either:
- Leave as wildcard (
*) to allow all branches - Specify specific branch names (e.g.,
main,develop)
- For "Environment", you can either:
- Leave as wildcard (
*) to allow all environments - Specify specific environment names (e.g.,
prod,staging)
This permission enables the OIDC token exchange that allows your GitHub Actions workflows to securely authenticate with the Atmos Pro API.
You can also deep-link directly to the permissions tab at
/repos/\{owner\}/\{repo\}/settings?tab=permissions.Now that you have configured your workspace, it's time to configure your Atmos stacks.
Ready to configure your Atmos stacks?
Now that you've configured your workspace, it's time to configure your Atmos stacks.