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:
- 1Validating the OIDC token and extracting repository context
- 2Looking up the repository's installation in the workspace
- 3Checking if the repository has the specific permission needed
- 4Verifying 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 theproduction
environment - Allow any workflow ending in
.yml
frommain
ordevelop
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
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:
- 1Extract Context: Parse the OIDC token to get repository, workflow, branch, and environment information
- 2Find Installation: Look up the GitHub App installation for the repository in the workspace
- 3Get Permissions: Retrieve all permissions configured for that installation
- 4Filter by Type: Find permissions that match the required permission type (e.g.,
ws:affected_stacks:create
) - 5Pattern Match: Check if any permission matches the current context using pattern matching
- 6Grant/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
*
) when first setting up permissions, then gradually restrict them for better securityUse 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.