Create and assign custom Deployment roles

Customize your users’ permissions for Airflow environments on Astro.

This is feature is only available if you are on the

Enterprise

tier or above. See

Astro Plans and Pricing

.

A user entity’s Deployment role determines their level of access to a specific Deployment in a Workspace. User entities with Workspace Member permissions or higher have some level of access to all Deployments in a Workspace, and these permissions can be increased using Deployment roles.

There are some circumstances where users should have limited access to Deployments in a Workspace. For example, all users might need full access to a development Deployment, but only administrative users need access to a production Deployment.

In situations where you need fine-grained Deployment access, you can create custom Deployment roles and assign them to users with Workspace Accessor or Workspace Member roles. If a user does not have a Workspace role when you assign them a Deployment role, Astro automatically gives them Workspace Accessor permissions. When you grant a user a Deployment role, they have a specific level of access to a specific Deployment. Use custom Deployment roles to enable users to collaborate in the same Workspace with only the minimum permissions they require.

Watch the Astro Academy Learning Byte video for

Custom Deployment Roles

to review some common use cases and learn more about how Astro implements RBAC.

Prerequisites

• Organization Owner permissions to create, update, and delete custom roles.
• Workspace Owner permissions or Deployment Admin permissions to assign and change Deployment roles for users.

See the User permissions reference for more information about user roles.

Create a custom Deployment role

You manage and create custom Deployment roles at the Organization level. After you create a custom Deployment role, you can assign users, teams, and Deployment API tokens the role from any Deployment in the Organization.

Deployment roles are additive, meaning that a user with multiple Deployment roles has all of the permissions of each Deployment role as well as their Workspace role. For example, if a user belongs to a Team with a custom Deployment role that includes permissions to edit Airflow variables, and they also have a personal custom Deployment role that includes permissions to edit connections, then the user has permissions to edit both Airflow variables and connections in the Deployment.

1. In the Astro UI, click Organization Settings.

2. Go to Access Management, then click Roles.

3. Click Custom then click + Add Role.

4. In the window that appears, confirm that the Scope dropdown is set to Deployment. To create a role scoped to individual Dags instead, select Dag. See Dag-level access control for more about Dag-scoped roles.

5. Enter a Name and Description for the role.

6. In the Permissions table, check the boxes of all permissions that you want the new role to have. See Custom role permissions reference for more information about each available permission.

   Use the dropdown menu above the permissions table to automatically load the permissions of a templated role or an existing custom role as the basis for your new role. See Deployment role templates for more information about the available default templates.

Custom Deployment role permissions

To deploy with the Astro CLI when using a Deployment API token with a custom Deployment role, the minimum required permissions for the token’s Deployment role are deployment.get and deployment.deploys.create.

7. Click Create role.

Your role is now available to assign at the Deployment level. See Assign users and Teams to Deployments or Create Deployment API tokens with custom Deployment roles for next steps.

Deployment role templates

Astro provides a few Deployment role templates that you can use as the basis for custom roles. These roles are not hard-coded and exist only as templates.

• Deployment Viewer: This is similar to the Airflow Viewer viewer role. It grants the user entity view-only permissions for the Airflow UI excluding the Admin tab.
• Deployment Author: This is similar to the Airflow User role. It grants the user entity permissions to deploy code and manage dag and task runs from the Airflow UI.
• Deployment Operator: This is similar to the Airflow Op role. It grants the user entity permissions to update Deployment API tokens and Airflow objects from both the Airflow UI and the Astro UI.
• Deployment Observe Ingest: This permission role allows a user entity permissions to ingest OpenLineage events and metrics.

Example: MCP_VIEWER role for the Airflow MCP Plugin

If you use the Airflow MCP Plugin to connect AI tools to your Deployment, create a custom MCP_VIEWER role with deployment.get and all deployment.airflow.*.get permissions. This is the least-privilege role that allows all MCP read tools to work. The MCP protocol requires POST requests, so the built-in WORKSPACE_MEMBER role does not work. See Configure authentication for setup instructions.

Assign users and Teams to Deployments

Using Deployment roles, you can add users and Teams directly to Deployments without first assigning them to a Workspace. If they don’t already belong to the Workspace, Astro grants them the Workspace Accessor role. A Workspace Accessor only has permissions to access their assigned Deployments within the Workspace. All other Deployments and Workspace settings are hidden.

1. In the Astro UI, open the Deployment where you want to assign the user entity.
2. Click Access, then click Users or Teams depending on what kind of user entity you want to assign to the Deployment.
3. Click + User/ + Team.
4. In the window that appears, select the user entity you want to add, then select the role they will have in the Deployment.
5. Click Add User/ Add Team.

Centralized access management for Organization Owners

Organization Owners can also add or update a user or Team for a Deployment from the Organization Settings:

1. In the Astro UI, click Organization Settings > Access Management.
2. Select the user or Team to add or update.
3. Click the Deployments tab, then click + Deployment to add them to a Deployment, or open the More actions menu (⋯) and select Edit role next to an existing Deployment to change their role.

Restrict a custom Deployment role to specific Workspaces

By default, a custom role is available to use in all Workspaces. After you create a custom Deployment role, you can restrict it so that users can only be assigned the role within specific Workspaces. Use Workspace role restriction when some Workspaces in your Organization have different requirements for how users interact with Deployments.

1. In the Astro UI, click Organization Settings.

2. Go to Access Management, then click Roles.

3. Click Custom, then select the custom role that you want to restrict.

4. In the menu that appears, click Restricted Workspaces, then click Edit.

5. Click the Workspace Restriction toggle to on, then tick the checkbox for any Workspaces where you want the role to be usable.

6. Click Update Restricted Workspaces.