Repository Permissions

Understand how Atmos Pro repository permissions control which workflows can access your workspace, and what GitHub Actions permissions your workflows need.

There are two separate permission concepts when using Atmos Pro:

1
Atmos Pro repository permissions — control which workflows, branches, and environments are authorized to interact with your Atmos Pro workspace. These are configured in the Atmos Pro dashboard.
2
GitHub Actions workflow permissions — the permissions: block in your workflow YAML that grants your workflow access to GitHub features like OIDC tokens and status checks.

Your GitHub Actions workflows need these permissions to work with Atmos Pro:

permissions block in your workflow YAML

permissions:
  id-token: write # Required for OIDC authentication with Atmos Pro and your cloud provider
  contents: read # Required for actions/checkout
  checks: write # Required for Atmos to set GitHub Actions statuses
  statuses: write # Required to post status checks back to PR commits

These are standard GitHub Actions permissions and are the same across all Atmos Pro workflows (plan, apply, list instances, etc.).

Atmos Pro uses a permission system to control which GitHub repositories can access your workspace and perform specific actions. These permissions are configured in the Atmos Pro dashboard and determine what your workflows are allowed to do within Atmos Pro.

With repository permissions, you can:

Control which repositories can access your workspace

Enforce security policies for infrastructure deployments

Limit access to sensitive environments

Maintain a secure and compliant workflow

Use granular pattern matching for workflows, branches, and environments

Atmos Pro's permission system operates at multiple levels to ensure secure access control:

Repository Permissions

Manage permissions for acme-org/infra

Affected Stacks Create

Allows workflows to upload affected stacks data for dependency analysis

Workflow:*

Branch:main

Environment:*

Deployments Create

Allows workflows to upload deployment information and track deployment history

Workflow:deploy-production.yml

Branch:main

Environment:production

Locks Create

Allows workflows to create stack locks to prevent concurrent deployments

Workflow:*

Branch:main

Environment:*

Locks Delete

Allows workflows to delete stack locks when deployments complete

Workflow:*

Branch:main

Environment:*

Preview Only

When a GitHub Actions workflow runs, it uses OpenID Connect (OIDC) to authenticate with Atmos Pro. The OIDC token contains information about:

The repository (owner/repo)
The workflow file being executed
The branch being deployed from
The environment (if specified)
The GitHub actor performing the action

Before allowing any API operation, Atmos Pro checks if the repository has the required permissions by:

1
Validating the OIDC token and extracting repository context
2
Looking up the repository's installation in the workspace
3
Checking if the repository has the specific permission needed
4
Verifying that the current workflow, branch, and environment match the permission configuration

Permissions support flexible pattern matching for workflows, branches, and environments:

Pattern Matching Examples

Matches everything (wildcard)

main

Exact match for main only

^(main|develop)$

Regex pattern matching main or develop

.*\.yml$

Regex pattern matching any file ending in .yml

prod.*

Regex pattern matching anything starting with prod

This allows you to create fine-grained permissions like:

Only allow deployments from the main branch to the production environment
Allow any workflow ending in .yml from main or develop branches
Restrict access to specific workflow files for sensitive operations

Atmos Pro provides several permission types that control different aspects of infrastructure management:

Permission Types

Affected Stacks Create

Allows workflows to upload affected stacks data for dependency analysis

Deployments Create

Allows workflows to upload deployment information and track deployment history

Locks Create

Allows workflows to create stack locks to prevent concurrent deployments

Locks Delete

Allows workflows to delete stack locks when deployments complete

This is the most commonly used permission. It allows GitHub Actions workflows to upload information about which stacks are affected by changes. This permission is required for:

Determining which infrastructure components need to be updated
Triggering workflow dispatches for affected stacks
Enabling ordered deployments based on dependencies

Permission Key:ws:affected_stacks:create

Permissions are configured at the repository level and include three key dimensions:

Specifies which GitHub Actions workflow files can use the permission.

Any workflow file

atmos-terraform-plan.yml

Specific workflow file

.*\\.yml$

Any file ending in .yml

When a GitHub Actions workflow makes a request to Atmos Pro, the permission system follows this logic:

1
Extract Context: Parse the OIDC token to get repository, workflow, branch, and environment information
2
Find Installation: Look up the GitHub App installation for the repository in the workspace
3
Get Permissions: Retrieve all permissions configured for that installation
4
Filter by Type: Find permissions that match the required permission type (e.g., ws:affected_stacks:create)
5
Pattern Match: Check if any permission matches the current context using pattern matching
6
Grant/Deny: Allow the request if a matching permission is found, otherwise return a 403 Forbidden error

Security Benefits of the Permission System:

Principle of Least Privilege: Each repository only gets the permissions it needs for its specific use case. A repository that only needs to report affected stacks doesn't get deployment permissions.

Environment Isolation: You can restrict sensitive operations (like production deployments) to specific environments, ensuring that only authorized workflows can affect critical infrastructure.

Workflow Granularity: By specifying exact workflow files, you can ensure that only trusted, reviewed workflows can perform sensitive operations.

Audit Trail: All permission checks are logged, providing a complete audit trail of which repositories accessed which features.

Here are some common permission configurations you might use:

Development Workflow

Permission: Affected Stacks Create
Workflow: "*"
Branch: "^(main|develop|feature/.*)$"
Environment: "*"

This allows any workflow from main, develop, or feature branches to report affected stacks.

Best Practices for Using Permissions:

Start with wildcards (`*`) when first setting up permissions, then gradually restrict them for better security

Use specific workflow file names rather than wildcards for production deployments or other sensitive operations

Leverage GitHub environments to add an extra layer of security for production deployments, requiring manual approval or additional checks

Periodically review your permission configurations to ensure they still match your security requirements and remove any unnecessary permissions

Test permission changes in a non-production environment first to ensure your workflows still function correctly

Ready to configure repository permissions?

Visit the workspace configuration page to set up permissions for your repositories.

Configure Permissions Next: Workflow Dispatches

Workflow Dispatches Troubleshooting

permissions: id-token: write # Required for OIDC authentication with Atmos Pro and your cloud provider contents: read # Required for actions/checkout checks: write # Required for Atmos to set GitHub Actions statuses statuses: write # Required to post status checks back to PR commits

Repository Permissions

With repository permissions, you can:

Control which repositories can access your workspace

Enforce security policies for infrastructure deployments

Limit access to sensitive environments

Maintain a secure and compliant workflow

Use granular pattern matching for workflows, branches, and environments

Repository Permissions

Affected Stacks Create

Deployments Create

Locks Create

Locks Delete

Pattern Matching Examples

Permission Types

Security Benefits of the Permission System:

Principle of Least Privilege: Each repository only gets the permissions it needs for its specific use case. A repository that only needs to report affected stacks doesn't get deployment permissions.

Environment Isolation: You can restrict sensitive operations (like production deployments) to specific environments, ensuring that only authorized workflows can affect critical infrastructure.

Workflow Granularity: By specifying exact workflow files, you can ensure that only trusted, reviewed workflows can perform sensitive operations.

Audit Trail: All permission checks are logged, providing a complete audit trail of which repositories accessed which features.

Development Workflow

Best Practices for Using Permissions:

Start with wildcards (*) when first setting up permissions, then gradually restrict them for better security

Use specific workflow file names rather than wildcards for production deployments or other sensitive operations

Leverage GitHub environments to add an extra layer of security for production deployments, requiring manual approval or additional checks

Periodically review your permission configurations to ensure they still match your security requirements and remove any unnecessary permissions

Test permission changes in a non-production environment first to ensure your workflows still function correctly

Ready to configure repository permissions?

Loading workspace data...

Repository Permissions

With repository permissions, you can:

Control which repositories can access your workspace

Enforce security policies for infrastructure deployments

Limit access to sensitive environments

Maintain a secure and compliant workflow

Use granular pattern matching for workflows, branches, and environments

Repository Permissions

Affected Stacks Create

Deployments Create

Locks Create

Locks Delete

Pattern Matching Examples

Permission Types

Security Benefits of the Permission System:

Principle of Least Privilege: Each repository only gets the permissions it needs for its specific use case. A repository that only needs to report affected stacks doesn't get deployment permissions.

Environment Isolation: You can restrict sensitive operations (like production deployments) to specific environments, ensuring that only authorized workflows can affect critical infrastructure.

Workflow Granularity: By specifying exact workflow files, you can ensure that only trusted, reviewed workflows can perform sensitive operations.

Audit Trail: All permission checks are logged, providing a complete audit trail of which repositories accessed which features.

Development Workflow

Best Practices for Using Permissions:

Start with wildcards (*) when first setting up permissions, then gradually restrict them for better security

Use specific workflow file names rather than wildcards for production deployments or other sensitive operations

Leverage GitHub environments to add an extra layer of security for production deployments, requiring manual approval or additional checks

Periodically review your permission configurations to ensure they still match your security requirements and remove any unnecessary permissions

Test permission changes in a non-production environment first to ensure your workflows still function correctly

Ready to configure repository permissions?

Start with wildcards (`*`) when first setting up permissions, then gradually restrict them for better security

Start with wildcards (`*`) when first setting up permissions, then gradually restrict them for better security