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.
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.com
- 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.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 the Dashboard: Go to the Atmos Pro dashboard and log in to your account
- 2Access Repository Management: Click on "Configured Repositories" in the main navigation menu
- 3Add New Repository: Click the "Add Repository" button (with the GitHub icon) in the top right corner
- 4Select Organization: Choose your GitHub organization from the dropdown menu
- 5Search and Select: Use the search field to find specific repositories, or browse through the list
- 6Import 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.