Role-Based Access Control (RBAC)

Up until recently, Spacelift used legacy system roles with broad roles (Reader, Writer, Admin) to manage user permissions. This approach worked for many organizations but lacked the granularity and flexibility needed for modern infrastructure management. With the introduction of the Custom RBAC system, Spacelift has transformed how permissions are managed, enabling a more fine-grained, composable approach to advanced access control.

Custom RBAC vs legacy system roles

Legacy system roles (previous approach)

The legacy system used three broad roles:

• Reader: View-only access to resources.
• Writer: Reader permissions + ability to trigger runs and modify environment variables.
• Admin: Writer permissions + ability to create/modify stacks and attachable entities.

Migration to custom RBAC

Existing legacy system role assignments have been automatically migrated to equivalent custom RBAC roles:

Legacy Role	RBAC Equivalent
Reader	Space Reader
Writer	Space Writer
Admin	Space Admin

Custom RBAC (current approach)

Custom RBAC decomposes these broad roles into individual, composable actions.

Custom RBAC Example

Instead of giving an actor, like an API key, full Writer access (which includes many permissions that are not needed), you can create a custom "Deployment Operator" role with just these permissions:

• run:trigger: Can trigger stack runs.
• run:read: Can view run details.

This approach provides exactly the access needed for deployment operations without extra permissions.

Core architecture

In Spacelift's RBAC system, actors are entities that perform actions on subjects within spaces. This architecture allows for precise control over who can do what, where, and how.

Actors: who performs actions

Actors include users, API keys, and IdP groups.

Users

Individual team members who are authenticated through your identity provider (GitHub, GitLab, Microsoft, Google, or SAML/OIDC SSO).

User patterns

• Use IdP groups for role assignment when possible.
• Limit individual user role assignments to exceptional cases.
• Regular access reviews and cleanup.

API Keys

Programmatic access tokens for automation and CI/CD integration.

API key patterns

• Create purpose-specific keys with minimal required permissions.
• Use specific custom roles rather than broad predefined roles.
• Use environment-specific keys rather than shared keys.
• Use descriptive names that indicate purpose (e.g., "terraform-ci-prod").
• Include environment or project context in the name.
• Implement key rotation policies.
• Document the purpose and owner of each API key.
• Monitor API key usage through audit trails.

IdP Groups

Groups of users as defined by your identity provider.

Examples of group sources

GitHub Teams:

• Passed in the users' token.

SAML/OIDC Groups:

• Defined by your enterprise identity provider.
• Mapped through SAML assertions or OIDC claims.
• Group membership determined by your IdP's group policies.

IdP group patterns

Functional Groups: Organize groups by job function across the organization.

• platform-engineers → Full infrastructure management
• application-developers → Deployment capabilities only
• security-auditors → Read-only access across all spaces

Project Groups: Organize groups by project or product.

• project-alpha-team → Full access to "Project Alpha" space
• project-beta-team → Full access to "Project Beta" space

Hybrid Approach: Combine functional and project-based groups.

• Base permissions from functional groups.
• Additional project-specific permissions from project groups.

Stacks

Stacks that can assume roles to manage resources programmatically inside Spacelift via the Spacelift Terraform Provider.

For more information, see Assigning Roles to Stacks.

Actions: the building blocks of permissions

Actions are the smallest unit of permission granularity in Spacelift's RBAC system. Each action defines a specific operation that can be performed:

Action	Description	Legacy Equivalent
run:trigger	Trigger stack runs	Writer
stack:manage	Create and modify stacks	Admin
stack:delete	Delete stacks	Admin
context:read	View contexts	Reader
context:manage	Create and modify contexts	Admin
space:read	View space contents	Reader
space:manage	Manage space settings	Admin

Expanding action catalog

The RBAC system supports a limited, but expanding set of actions. Spacelift continuously adds new actions based on user feedback and use cases.

Subjects: what actions are performed on

Subjects are the resources that actors interact with, for example:

• Stacks: Stacks managing infrastructure, runs, and associated metadata.
• Contexts: Environment variables, mounted files, and configuration collections.
• Policies: Rules governing Spacelift behavior (approval, notification, etc.).

Space-level granularity

Currently, RBAC operates at the space level. All roles are bound to specific spaces and apply equally to all subjects within that space. Entity-level granularity (e.g., permissions for individual stacks) is not yet supported.

Stack access patterns

Development Stacks:

• Developers need full management capabilities.
• Frequent deployments and experimentation.
• Less restrictive approval requirements.

Production Stacks:

• Limited management access to senior engineers.
• Strict approval workflows.
• Enhanced audit and monitoring.

Shared Infrastructure Stacks:

• Platform team management.
• Application team read access.
• Cross-team coordination requirements.

Policy access patterns

Centralized Governance:

• Security team manages all policies.
• Consistent rules across the organization.
• Limited policy creation permissions.

Federated Governance:

• Teams manage policies for their own spaces.
• Organization-wide baseline policies.
• Team-specific additional policies.

Spaces: the scope of permissions

All RBAC roles are space-bound, meaning:

• Roles are assigned to specific spaces.
• Permissions apply to all subjects within that space.
• Users need appropriate roles in each space they need to access.

Space hierarchy

Spaces can be organized hierarchically to reflect your organizational structure:

graph TD
    Root["Root Space"]
    Infrastructure["Infrastructure<br/>(Platform team management)"]
    Networking[Networking]
    Security[Security]
    Monitoring[Monitoring]
    Applications["Applications<br/>(Application teams)"]
    Frontend[Frontend]
    Backend[Backend]
    Mobile[Mobile]
    Sandbox["Sandbox<br/>(Development and testing)"]

    Root --> Infrastructure
    Root --> Applications
    Root --> Sandbox
    Infrastructure --> Networking
    Infrastructure --> Security
    Infrastructure --> Monitoring
    Applications --> Frontend
    Applications --> Backend
    Applications --> Mobile

Space design patterns

Isolation requirements:

• Separate spaces for different environments (dev/staging/prod).
• Separate spaces for different teams or projects.
• Separate spaces for different compliance requirements.

Permission boundaries:

• Align space boundaries with permission requirements.
• Consider who needs access to what resources.
• Plan for space hierarchy and inheritance patterns.

Roles

System roles

System roles provide standard, least-privileged permission policies for granting access to specific pieces of Spacelift functionality. For example, the Worker pool controller role contains the correct permissions to allow the Kubernetes controller to manage worker pools automatically.

System roles are immutable and cannot be modified or deleted, ensuring consistent baseline permissions across all accounts.

Space reader

Actions: Basic read permissions

• View stacks, contexts, policies, and runs.
• Add comments to runs for feedback.
• Cannot trigger actions or modify resources.
• Equivalent to legacy Reader role.

Space writer

Actions: Space Reader + multiple execution permissions

• All Space Reader permissions.
• Trigger stack runs.
• Execute tasks.
• Modify stack environment variables.
• Equivalent to legacy Writer role.

Space admin

Actions: Space Writer + management permissions

• All Space Writer permissions.
• Create and modify stacks.
• Create and modify contexts and policies.
• Manage space settings (when assigned to specific space).
• View all roles, users, API keys, and IdP group mappings in the organization (read-only).
• Manage role bindings (assign/remove roles) for users, API keys, and IdP groups within the spaces they administer.
• Equivalent to legacy Admin role.

Root Space Admin vs Non-root Space Admin

Root Space Admins (Space Admin role on the root space) have account-wide privileges including:

• All Space Admin permissions across all spaces
• SSO setup, VCS configuration, audit trail management
• Invite/revoke users and create/modify/delete roles
• Create/modify/delete API keys and IdP group mappings
• Manage role bindings across all spaces

Non-root Space Admins (Space Admin role on any non-root space) have limited privileges:

• Space Admin permissions only within the spaces they administer
• Can view all roles, users, API keys, and IdP group mappings
• Can manage role bindings only for the spaces they administer
• Cannot invite/revoke users, create/modify/delete roles, or create/modify/delete API keys and IdP group mappings

Worker pool controller

Actions:

• Space
  • Read
• Workerpool
  • Create
  • Update
  • Delete

Custom roles

Create custom roles using the web UI

1. Go to Organization Settings → Access Control Center → Roles.
2. Click Create Role to start defining a new role.
3. Define Role Properties:
   • Name: Descriptive role name (e.g., "Infrastructure Developer").
   • Description: Clear explanation of the role's purpose.
   • Actions: Select specific permissions needed.

Read access baseline

The space:read action is required to view any subjects within a space. Without it, users cannot see other resources even if they have permissions for them.

Create custom roles using the Terraform provider

Refer to the Spacelift Terraform provider documentation for detailed instructions on creating custom roles programmatically.

Role bindings (assigning roles to actors)

View more detailed instructions for assigning roles to:

• Individual users
• API keys
• IdP groups
• Stacks