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:
  1. 1
    Log in to your Atmos Pro app at atmos-pro.com
  2. 2
    Click on the "Workspace Settings" (gear icon) in the bottom left corner
  3. 3
    Your 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:
  1. 1
    Navigate to the Dashboard: Go to the Atmos Pro dashboard and log in to your account
  2. 2
    Access Repository Management: Click on "Configured Repositories" in the main navigation menu
  3. 3
    Add New Repository: Click the "Add Repository" button (with the GitHub icon) in the top right corner
  4. 4
    Select Organization: Choose your GitHub organization from the dropdown menu
  5. 5
    Search and Select: Use the search field to find specific repositories, or browse through the list
  6. 6
    Import 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 Affected Stacks Create permission. This permission is required for the OIDC token exchange between your GitHub Actions workflows and the Atmos Pro API.
How it works
To configure the required permission:
  1. 1
    Go to the Atmos Pro dashboard
  2. 2
    Navigate to the "Configured Repositories" menu
  3. 3
    Find your repository in the list
  4. 4
    Click the settings icon (gear) next to your repository
  5. 5
    Click "Permissions" in the settings menu
  6. 6
    Click "Add Permissions"
  7. 7
    In 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.

Configure Atmos StacksLearn about Atmos Stacks
TroubleshootingAtmos Stacks