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:

Runs: Trigger run: Can trigger stack runs.
Space: Read: Can view stacks, runs, and other resources within the space.

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. Actions are organized by subject type (the resource they operate on).

Legacy role fallbacks

When a user doesn't have an explicit action permission through a custom role, the system falls back to checking their legacy space access level (Reader/Writer/Admin). The "Legacy Fallback" column indicates which legacy role is required when custom action permissions are not granted.

Space actions»

Action	Description	Legacy Fallback
Admin	Full administrative access to a space	Admin
Read	Grants visibility into stacks, runs, and other resources within an assigned space. Required to view any subjects within a space	Reader
Write	Write access to space resources	Writer
Share module	Allow modules to be shared with an assigned space from other spaces	Writer

Run actions»

Action	Description	Legacy Fallback
Cancel run	Cancel runs in a given space	Reader
Cancel blocking run	Cancel blocking runs in a given space	Writer
Comment on run	Comment on runs in a given space	Reader
Confirm run	Confirm a plan and apply changes	Writer
Discard run	Discard planned changes	Writer
Prioritize run	Prioritize a run in a given space	Writer
Promote run	Trigger a tracked run for the same Git commit as a proposed run	Writer
Propose run from local workspace	Trigger a proposed run based on local workspace	Writer
Propose run with overrides	Trigger a proposed run with environment variable overrides	Writer
Retry run	Retry runs in a given space	Reader
Retry blocking run	Retry blocking runs in a given space	Writer
Review run	Review the planned changes and submit a review (approval/rejection). Does not replace the approval policy	Writer
Stop run	Stop runs in a given space	Reader
Stop blocking run	Stop blocking runs in a given space	Writer
Replan targeted run	Replan a targeted run in a given space	Writer
Trigger run	Trigger stack runs in a given space	Writer
Trigger run with custom runtime config	Trigger stack runs in a given space with custom runtime config	Admin

Task actions»

Action	Description	Legacy Fallback
Create task	Trigger tasks for stacks in a given space	Writer

Stack actions»

Action	Description	Legacy Fallback
Add stack config	Adds or updates stack environment variables and mounted files	Writer
Create stack	Create stacks in a given space	Admin
Delete stack	Delete stacks in a given space	Admin
Delete stack config	Deletes stack environment variables and mounted files	Writer
Disable stack	Disable a stack	Admin
Enable stack	Enable a disabled stack	Admin
Lock stack	Locks a stack for exclusive use and prevents operations by other users	Writer
Manage stack	Manage stacks in a given space.	Admin
Rollback stack managed state	Rollback managed state for a stack	Admin
Re-slug stack	Re-slug stacks in a given space	Admin
Set stack current commit	Set stack current commit in a given space	Writer
Download stack state	Download the state file for a stack	Writer
Sync stack commit	Sync the tracked branch head commit with the head commit of the stack	Writer
Unlock stack	Unlocks a previously locked stack, only if locked by the same user	Writer
Force unlock stack	Unlocks any locked stack, including those locked by other users	Admin
Update stack	Update stacks in a given space (details, source, behavior, vendor)	Admin
Upload local workspace for stack	Generate upload URLs for local previews	Writer

Context actions»

Action	Description	Legacy Fallback
Create context	Create contexts in a given space	Admin
Delete context	Delete contexts in a given space	Admin
Update context	Update contexts in a given space	Admin

Worker Pool actions»

Action	Description	Legacy Fallback
Drain worker	Drain or undrain workers in a given space	Admin
Create worker pool	Create worker pools in a given space	Admin
Cycle worker pool	Cycle worker pools in a given space	Admin
Delete worker pool	Delete worker pools in a given space	Admin
Reset worker pool	Reset worker pools in a given space	Admin
Update worker pool	Update worker pools in a given space	Admin

Module actions»

Action	Description	Legacy Fallback
Create module	Create a module	Admin
Disable module	Disable a module	Admin
Enable module	Enable a module	Admin
Mark module as bad	Mark a module as bad	Writer
Publish module	Publish a module	Admin
Trigger module version	Trigger a module version	Writer

Terraform Provider actions»

Action	Description	Legacy Fallback
Create Terraform provider	Create Terraform provider in a given space	Admin
Delete Terraform provider	Delete Terraform provider in a given space	Admin
Set Terraform provider visibility	Set visibility for Terraform providers	Admin
Update Terraform provider	Update Terraform provider in a given space	Admin
Create Terraform provider version	Create Terraform provider version in a given space	Writer
Delete Terraform provider version	Delete Terraform provider version in a given space	Writer
Publish Terraform provider version	Publish Terraform provider version in a given space	Writer
Register Terraform provider version platform	Register platform for Terraform provider versions	Writer
Revoke Terraform provider version	Revoke Terraform provider version in a given space	Writer
Update Terraform provider version	Update Terraform provider version in a given space	Writer

Intent actions»

Intent actions are used for managing Intent-based infrastructure.

Action	Description	Legacy Fallback
Add intent dependencies	Add dependencies to intent project	Admin
Remove intent dependencies	Remove dependencies from intent project	Admin
Create intent policies	Create new intent policies	Admin
Delete intent policies	Delete intent policies	Admin
Update intent policies	Update existing intent policies	Admin
Attach AWS integration to intent project	Attach AWS integration to an intent project	Admin
Detach AWS integration from intent project	Detach AWS integration from an intent project	Admin
Add intent project config	Add configuration to an intent project	Admin
Delete intent project config	Delete configuration from an intent project	Admin
Update intent project config	Update configuration in an intent project	Admin
Create intent project	Create a new intent project	Admin
Delete intent project	Delete an intent project	Admin
Disable intent project	Disable an intent project	Admin
Enable intent project	Enable an intent project	Admin
Lock intent project	Lock an intent project	Admin
Attach policy to intent project	Attach a policy to an intent project	Admin
Detach policy from intent project	Detach a policy from an intent project	Admin
Unlock intent project	Unlock an intent project	Admin
Update intent project	Update an intent project	Admin
Create intent resources	Create new cloud resources	Admin
Delete intent resources	Delete cloud resources	Admin
Import intent resources	Import existing cloud resources into state	Admin
Refresh intent resources	Refresh cloud resource state	Admin
Resume intent resources	Resume intent resource operations	Admin
Update intent resources	Update existing cloud resources	Admin
Review intent resource operation	Review an intent resource operation	Admin
Eject from intent state	Eject resources from state	Admin
Read intent state	Read intent state details	Admin

Drift Detection actions»

These actions manage drift detection integrations.

Action	Description	Legacy Fallback
Create drift detection integration	Create drift detection for a stack	Admin
Update drift detection integration	Update drift detection for a stack	Admin
Delete drift detection integration	Delete drift detection for a stack	Admin

Template actions»

These actions manage Templates and their deployments.

Action	Description	Legacy Fallback
Create template	Create a template	Admin
Update template	Update a template	Admin
Delete template	Delete a template	Admin
Create template deployment	Create a deployment from a template	Admin
Update deployment inputs	Update inputs for a template deployment	Admin
Upgrade deployment version	Upgrade a template deployment version	Admin
Delete template deployment	Delete a template deployment	Admin

Action catalog expansion

Spacelift continuously adds new actions based on user feedback and use cases. If you need an action that isn't currently available, please contact Spacelift support.

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.
Create and modify Intent projects.
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»

Go to Organization Settings → Access Control Center → Roles.
Click Create Role to start defining a new role.
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 Read (Space) 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: