Docs for stack role assumptions

Author: peterdeme

docs/assets/screenshots/role_stacks_migration.png

@@ -29,12 +29,13 @@ RBAC operates on three fundamental concepts: actions, actors, and subjects.
 - **Users**: Individual team members authenticated through your identity provider.
 - **API Keys**: Programmatic access tokens for automation.
 - **IdP Groups**: Groups of users as defined by your identity provider.
+- **Stacks**: Stacks that can assume roles to make changes inside of Spacelift.
 
 ### Subjects
 
 **Subjects** are the resources being acted upon. Examples include:
 
-- **Stacks**: Infrastructure definitions and their runs.
+- **Stacks**: Stacks managing infrastructure and their runs.
 - **Contexts**: Collections of environment variables and files.
 - **Policies**: Rules that govern various Spacelift behaviors.
 - **Spaces**: Organizational containers for resources.

docs/concepts/authorization/README.md

@@ -0,0 +1,285 @@
+# Stack role attachments
+
+Stacks can receive role bindings to perform operations with elevated permissions, similar to how users, API keys, and IdP groups receive permissions through [Spacelift's RBAC system](rbac-system.md).
+
+Stack role attachments replace the deprecated [Administrative](../stack/stack-settings.md#administrative) flag, providing a more flexible, auditable, and powerful approach to granting stacks elevated permissions.
+
+## Why use stack role attachments
+
+Stack role attachments offer significant advantages over the deprecated administrative flag:
+
+### Cross-space access
+
+**Administrative flag limitation**: Can only create resources in the stack's own space and subspaces.
+
+**Role attachments advantage**: Can attach roles to sibling spaces, enabling horizontal access across the space tree. In the example below, a stack in `ChildSpace1` can be granted access to `ChildSpace2`:
+
+```mermaid
+graph TD
+    A[root] --> B[ChildSpace1]
+    A --> C[ChildSpace2]
+```
+
+### Fine-grained access control
+
+**Administrative flag limitation**: All-or-nothing approach - grants full Space Admin permission with every available permission.
+
+**Role attachments advantage**: Use custom roles with specific permissions (for example, only `context:create` and `workerpool:create`).
+
+This means a stack can create contexts and worker pools, but cannot manage any other resources, such as policies or webhooks.
+
+### Enhanced audit trail
+
+**Administrative flag**: Basic audit trail with stack actor information.
+
+**Role attachments advantage**: Audit trail webhooks include role information in the `ActorRoles` field (array of role slugs).
+
+This provides better visibility into what permissions the stack was using when performing actions. See the [audit trail documentation](../../integrations/audit-trail.md) for details.
+
+### Modern RBAC consistency
+
+Role attachments align stacks with the broader role-based access model already used by [users](./assigning-roles-users.md), [IdP groups](./assigning-roles-groups.md), and [API keys](./assigning-roles-api-keys.md), providing a consistent permission management experience across all actors.
+
+## Assign roles to stacks
+
+### Prerequisites
+
+To attach a role to a stack, you need:
+
+- `StackManage` permission (or `SpaceAdmin` permission as fallback) to the stack's space
+- `SpaceAdmin` permission to the binding space (the space where the role will be effective)
+
+!!! info "Why both permissions are required"
+    Creating a role binding that grants permissions to a space effectively allows the stack to act in that space. To prevent privilege escalation, you must have admin access to both spaces: the space where the stack resides and the space where the role will be effective.
+
+### Using the Web UI
+
+1. Navigate to the stack's **Settings** page, then choose **Roles** on the left
+2. Click **Manage Roles** on the top right
+3. In the sidebar, select the desired role and the target space
+4. Click **Add**
+
+### Using the Terraform provider
+
+Use the `spacelift_role_attachment` resource:
+
+```hcl
+resource "spacelift_stack" "admin" {
+  name        = "Admin stack"
+  repository  = "spacelift-resources"
+  description = "Only has permissions to create another stacks in the dev space"
+  branch      = "main"
+}
+
+resource "spacelift_role" "stack_creator" {
+  name        = "Stack creator"
+  description = "A role solely for creating stacks"
+  actions     = ["STACK_MANAGE"]
+}
+
+resource "spacelift_space" "dev" {
+  name            = "dev"
+  parent_space_id = "root"
+}
+
+resource "spacelift_role_attachment" "stack_creator_to_admin_stack" {
+  stack_id = spacelift_stack.admin.id
+  role_id  = spacelift_role.stack_creator.id
+  space_id = spacelift_space.dev.id
+}
+```
+
+For more information, see the [Spacelift Terraform provider documentation](https://search.opentofu.org/provider/spacelift-io/spacelift/latest/docs/resources/role_attachment){: rel="nofollow"}.
+
+## Permission cascading
+
+Role attachments cascade down to child spaces, similar to how the administrative flag worked:
+
+```text
+parentSpace
+├── childSpace1
+└── childSpace2
+    └── grandchildSpace
+```
+
+If a role is attached to `parentSpace`, the same role will be effective in `childSpace1`, `childSpace2`, and `grandchildSpace`.
+
+!!! warning "Root space caution"
+    Since the `root` space is the parent of all spaces, attaching roles to it affects **all spaces** in your account. Use this with extreme caution and only when necessary.
+
+## Administrative flag precedence
+
+The administrative flag takes precedence over role attachments:
+
+- If `administrative = true`, any attached roles will be **completely ineffective**
+- You **must** set `administrative = false` for role attachments to take effect
+- This is critical for migration - disable the administrative flag after creating role attachments
+
+## Policy integration
+
+Policies can react to stack role attachments through the `stack.roles` field in [policy inputs](../policy/approval-policy.md#data-input-schema). This enables policy-based logic based on what roles a stack has attached.
+
+### Example: Reject Space Admin role usage
+
+```rego
+package spacelift
+
+reject_with_note["Don't use the Space Admin role!"] {
+  role := input.stack.roles[_]
+  role.id == "space-admin" # Role slug. Use the "Copy Slug" button in the UI to get it.
+}
+```
+
+## Multiple roles
+
+Stacks can have multiple role bindings:
+
+- Different roles in different spaces for varied access levels
+- Multiple roles in the same space (permissions are additive)
+- Combinations of Space Admin in own space and Reader in other spaces
+
+### Example: Multiple role attachments
+
+```hcl
+# Admin access to development space
+resource "spacelift_role_attachment" "dev_admin" {
+  stack_id = spacelift_stack.platform.id
+  role_id  = "space-admin"
+  space_id = "development-space-id"
+}
+
+# Read access to production space
+resource "spacelift_role_attachment" "prod_reader" {
+  stack_id = spacelift_stack.platform.id
+  role_id  = "space-reader"
+  space_id = "production-space-id"
+}
+```
+
+## External state access
+
+External state access allows you to read the state of the stack from outside authorized runs and [tasks](../../concepts/run/task.md). See the documentation [here](../../vendors/terraform/external-state-access.md) for further details.
+
+In order for your stack to access another stack's OpenTofu/Terraform state, the stack needs to have **Space writer** role to the target stack's space. This can be achieved by attaching the **Space writer** role to the stack for the target stack's space.
+
+Example:
+
+```hcl
+data "spacelift_role" "space_writer" {
+  slug = "space-writer"
+}
+
+resource "spacelift_role_attachment" "space_writer" {
+  stack_id = spacelift_stack.consumer.id
+  role_id  = data.spacelift_role.space_writer.id
+  space_id = spacelift_stack.provider.space_id
+}
+```
+
+!!! note
+    The **Space admin** role also includes **Space writer** permissions.
+
+## Migration from administrative flag
+
+!!! warning "Automatic Migration on June 1st, 2026"
+    On June 1st, 2026, Spacelift will automatically disable all administrative flags and attach the Space Admin role to each stack's own space. This automatic migration is **100% backward compatible** and ensures no functionality loss.
+
+    However, **manual migration is strongly recommended** to take advantage of advanced features like cross-space access and fine-grained permissions that are not available with automatic migration.
+
+### What happens on June 1st, 2026
+
+On June 1st, 2026, Spacelift will automatically:
+
+- Disable all administrative flags
+- Attach the Space Admin role to each stack's own space (100% backward compatible)
+    - Note: if you move the stack to a different space later, the role attachment remains unchanged and will not follow the stack's new space 
+- Remove the administrative flag from the UI
+- Make the flag ineffective in the GraphQL API (even if set to `true`, it will behave as `false`)
+
+### Step-by-step migration guide
+
+#### 1. Identify stacks with administrative flag
+
+List all stacks with `administrative = true` in your account. You can do this through the Spacelift UI (by filtering on the stacks page) or by searching your Terraform code for the `administrative` attribute.
+
+#### 2. For each stack, create role attachment
+
+Attach the Space Admin role to the stack using the stack's own space as the binding space:
+
+**Using the Terraform provider:**
+
+```hcl
+data "spacelift_role" "admin_role" {
+  slug = "space-admin"
+}
+      
+resource "spacelift_role_attachment" "stack_admin" {
+  stack_id = spacelift_stack.management.id
+  space_id = spacelift_stack.management.space_id
+  role_id  = data.spacelift_role.admin_role.id
+}
+```
+
+**Using the Web UI:**
+
+1. Navigate to the stack's **Settings** page, then choose **Roles**
+2. Click **Manage Roles** on the top right
+3. In the drawer, select the **Space admin** role and the stack's own Space as the target
+4. Click **Add**
+
+Assuming your stack is in the `dev` [Space](../spaces/README.md), the role attachment will grant **Space admin** permissions in the `dev` space:
+
+![](../../assets/screenshots/role_stacks_migration.png)
+
+#### 3. Disable the administrative flag
+
+Once you've verified the roles have been attached, disable the administrative flag:
+
+```hcl
+resource "spacelift_stack" "management" {
+  # [... other stack settings ...]
+  administrative = false
+}
+```
+
+!!! important
+    The administrative flag takes precedence over role attachments. If `administrative = true`, any attached roles will be ignored. You must set `administrative = false` for role attachments to take effect.
+
+#### 4. Verify the role attachment
+
+After creating the role attachment, verify that the stack can perform the same operations as before. Trigger a tracked run and ensure it succeeds.
+
+#### 5. Adjust policies if necessary
+
+If any of your policies reference the `stack.administrative` field, update them to use the `stack.roles` field instead. For example:
+
+```rego
+# Old policy:
+deny_with_note["Administrative stacks are not allowed"] {
+  stack := input.stack
+  stack.administrative == true
+}
+
+# Would become:
+deny_with_note["Administrative stacks are not allowed"] {
+  role := input.stack.roles[_]
+  role.id == "space-admin" # Role slug. Use the "Copy Slug" button in the UI to get it.
+}
+```
+
+### Rollback procedure
+
+If you need to roll back during migration:
+
+1. Set `administrative = true` again
+2. The administrative flag takes precedence, so role attachments will be ignored
+3. Test that everything works as before
+4. You can leave the role attachments in place and try migration again later
+
+## Edge cases
+
+### Stack moving between spaces
+
+When a stack moves to a different space, existing role bindings remain unchanged. This is intentional and important for Terraform provider stability.
+
+If you want to update role bindings after moving a stack, you need to explicitly modify the role attachments.

docs/concepts/authorization/assigning-roles-stacks.md

@@ -19,7 +19,7 @@ The legacy system used three broad roles:
     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     |
@@ -104,13 +104,19 @@ Groups of users as defined by your identity provider.
 - Base permissions from functional groups.
 - Additional project-specific permissions from project groups.
 
+#### Stacks
+
+[Stacks](../stack/README.md) that can assume roles to manage resources programmatically inside Spacelift via the [Spacelift Terraform Provider](https://search.opentofu.org/provider/spacelift-io/spacelift/latest){: rel="nofollow"}.
+
+For more information, see [Assigning Roles to Stacks](./assigning-roles-stacks.md).
+
 ### 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             |
@@ -126,7 +132,7 @@ operation that can be performed:
 
 Subjects are the resources that actors interact with, for example:
 
-- **Stacks**: Infrastructure definitions, runs, and associated metadata.
+- **Stacks**: Stacks managing infrastructure, runs, and associated metadata.
 - **Contexts**: Environment variables, mounted files, and configuration collections.
 - **Policies**: Rules governing Spacelift behavior (approval, notification, etc.).
 
@@ -269,3 +275,4 @@ View more detailed instructions for assigning roles to:
 - [Individual users](./assigning-roles-users.md)
 - [API keys](./assigning-roles-api-keys.md)
 - [IdP groups](./assigning-roles-groups.md)
+- [Stacks](./assigning-roles-stacks.md)

docs/concepts/authorization/rbac-system.md

@@ -5,7 +5,7 @@
     This feature is only available on the Business plan and above. Please check out our [pricing page](https://spacelift.io/pricing){: rel="nofollow"} for more information.
 {% endif %}
 
-There are multiple ways to create [stacks](../stack/README.md) in Spacelift. We recommend using [our Terraform provider](../../vendors/terraform/terraform-provider.md) to programmatically create stacks using an [administrative](../stack/stack-settings.md#administrative) stack.
+There are multiple ways to create [stacks](../stack/README.md) in Spacelift. We recommend using [our Terraform provider](../../vendors/terraform/terraform-provider.md) to programmatically create stacks using a stack with appropiate [role attachments](../authorization/assigning-roles-stacks.md).
 
 However, some users might not be comfortable using Terraform code to create stacks. This is where Blueprints come in handy.
 
@@ -17,7 +17,7 @@ You can configure the following resources in a Blueprint:
 
 - All [stack settings](../stack/stack-settings.md) including:
     - Name, description, labels, [space](../spaces/README.md).
-    - **Behavioral settings**: administrative, auto-apply, auto-destroy, hooks, runner image, etc.
+    - **Behavioral settings**: auto-apply, auto-destroy, hooks, runner image, etc.
 - [VCS configuration](../../integrations/source-control/README.md).
     - Both default and space-level VCS integrations. In GitHub, custom app installations can only be created by GitHub Enterprise accounts.
 - Vendor configuration for your IaC provider.
@@ -169,7 +169,7 @@ inputs:
             - Owner/${{ context.user.login }}
             - Blueprint/${{ context.blueprint.name }}
             - Space/${{ context.blueprint.space }}
-        administrative: false
+        administrative: false # Deprecated in favor of role attachments
         allow_promotion: false
         auto_deploy: false
         auto_retry: false

docs/concepts/blueprint/README.md

@@ -80,8 +80,8 @@ This step enables you to attach the context to projects without navigating to th
 
 In this step, you have the option to configure environment variables and mounted files if you already have them ready during the creation of the context.
 
-| Environment variables | Mounted files |
-| - | - |
+| Environment variables                                           | Mounted files                                                   |
+| --------------------------------------------------------------- | --------------------------------------------------------------- |
 | ![](../../assets/screenshots/context/creation_form_step_2a.png) | ![](../../assets/screenshots/context/creation_form_step_2b.png) |
 
 #### Step 4 - Add hooks (optional)
@@ -293,11 +293,11 @@ A variation of this use case is collections of [OpenTofu/Terraform input variabl
 If the data in the context is produced by one or more Spacelift stacks, contexts can be an attractive alternative to the Terraform [remote state](https://www.terraform.io/docs/providers/terraform/d/remote_state.html){: rel="nofollow"}. In this use case, contexts can serve as outputs for stacks that can be consumed by (attached to) other stacks. So, instead of exposing the entire state, a stack can use Spacelift Terraform provider to define values on a context - either managed by the same stack , or managed externally. Managing a context externally can be particularly useful when multiple stacks contribute to a particular context.
 
 !!! info
-    In order to use the Terraform provider to define contexts or its configuration elements the stack has to be marked as [administrative](../stack/README.md#administrative).
+    In order to use the Terraform provider to define contexts or its configuration elements the stack has to have appropiate [role attachments](../authorization/assigning-roles-stacks.md).
 
 As an example of one such use case, let's imagine an organization where shared infrastructure (VPC, DNS, compute cluster etc.) is centrally managed by a DevOps team, which exposes it as a service to be used by individual product development teams. In order to be able to use the shared infrastructure, each team needs to address multiple entities that are generated by the central infra repo. In vanilla Terraform one would likely use remote state provider, but that might expose secrets and settings the DevOps team would rather keep it to themselves. Using a context on the other hand allows the team to decide (and hopefully document) what constitutes their "external API".
 
-The proposed setup for the above use case would involve two administrative stacks - one to manage all the stacks, and the other for the DevOps team. The management stack would programmatically define the DevOps one, and possibly also its context. The DevOps team would receive the context ID as an input variable, and use it to expose outputs as [`spacelift_environment_variable`](https://github.com/spacelift-io/terraform-provider-spacelift#spacelift_environment_variable-resource){: rel="nofollow"} and/or [`spacelift_mounted_file`](https://github.com/spacelift-io/terraform-provider-spacelift#spacelift_mounted_file-resource){: rel="nofollow"} resources. The management stack could then simply attach the context populated by the DevOps stack to other stacks it defines and manages.
+The proposed setup for the above use case would involve two [stacks with roles](../authorization/assigning-roles-stacks.md) - one to manage all the stacks, and the other for the DevOps team. The management stack would programmatically define the DevOps one, and possibly also its context. The DevOps team would receive the context ID as an input variable, and use it to expose outputs as [`spacelift_environment_variable`](https://github.com/spacelift-io/terraform-provider-spacelift#spacelift_environment_variable-resource){: rel="nofollow"} and/or [`spacelift_mounted_file`](https://github.com/spacelift-io/terraform-provider-spacelift#spacelift_mounted_file-resource){: rel="nofollow"} resources. The management stack could then simply attach the context populated by the DevOps stack to other stacks it defines and manages.
 
 ### Extending Terraform CLI Configuration (Terraform-specific)