Permissions

Understand how repository permissions work in Atmos Pro and how they control access to your infrastructure deployments.

Atmos Pro uses a sophisticated permission system to control which GitHub repositories can access your workspace and perform specific actions. This system ensures that only authorized CI/CD workflows can interact with your infrastructure deployments, providing security and compliance for your infrastructure management.

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:
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. 1
    Validating the OIDC token and extracting repository context
  2. 2
    Looking up the repository's installation in the workspace
  3. 3
    Checking if the repository has the specific permission needed
  4. 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. 1
    Extract Context: Parse the OIDC token to get repository, workflow, branch, and environment information
  2. 2
    Find Installation: Look up the GitHub App installation for the repository in the workspace
  3. 3
    Get Permissions: Retrieve all permissions configured for that installation
  4. 4
    Filter by Type: Find permissions that match the required permission type (e.g., ws:affected_stacks:create)
  5. 5
    Pattern Match: Check if any permission matches the current context using pattern matching
  6. 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 PermissionsNext: Workflow Dispatches
Workflow DispatchesTroubleshooting