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, you'll need to add it to your GitHub repository as a variable. You can do this by following the GitHub documentation to define configuration variables either the organization, repository, or environment level.
The variable should be named
ATMOS_PRO_WORKSPACE_ID and should be set to your workspace ID.Actions secrets and variables
Secrets and variables allow you to manage reusable configuration data. Secrets are encrypted and are used for sensitive data. Learn more about encrypted secrets. Variables are shown as plain text and are used for non-sensitive data. Learn more about variables.
Anyone with collaborator access to this repository can use these secrets and variables for actions. They are not passed to workflows that are triggered by a pull request from a fork.
SecretsVariables
Environment variables
This environment has no variables.
Manage environment variables
Repository variables
New repository variableName ↕
Value
Last updated
ATMOS_PRO_WORKSPACE_ID
ws_xxxxxxxxxxxxxxxxxxxx
2 months ago
ATMOS_VERSION
latest
last week
Workspace ID is not sensitive
The workspace ID is used as part of GitHub OIDC exchange to authenticate workflows with the correct workspace.
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
- 5Click "Permissions" in the settings menu
- 6Click "Add Permissions"
- 7In the permissions dialog:
- 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.
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.