> ## Documentation Index
> Fetch the complete documentation index at: https://astronomer.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Create and assign custom Deployment roles
This is feature is only available if you are on the **Enterprise** tier or above. See [Astro Plans and Pricing](https://www.astronomer.io/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](/docs/astro/user-permissions#workspace-roles) 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 doesn't 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](https://academy.astronomer.io/learning-bytes-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](/docs/astro/user-permissions) for more information about user roles.
**A new Astro UI is here**
Astronomer has redesigned the Astro UI. Try the new experience and switch your instructions using the **New Astro UI** and **Legacy UI** tabs on this page. Your selection is remembered across the docs.
## 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, go to **Settings**, then in the **Access Management** section, click **Roles & Permissions**.
2. Click **Custom**, then click **+ New Custom Role**.
3. In the **New Role** dialog, 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](/docs/astro/dag-level-access-control#create-a-custom-dag-role) for more about Dag-scoped roles.
4. Enter a **Name** and **Description** for the role.
5. In the **Permissions** table, select all permissions that you want the new role to have. See [Custom role permissions reference](/docs/astro/deployment-role-reference) for more information about each available permission.
To base the new role on an existing one, use the **Copy from an existing role or template** dropdown above the table. See [Deployment role templates](#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`](/docs/astro/deployment-role-reference#deployment) and [`deployment.deploys.create`](/docs/astro/deployment-role-reference#deployment-deploys).
6. Click **Create Role**.
1. In the Astro UI, click **Organization Settings** > **Access Management**.
2. 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](/docs/astro/dag-level-access-control#create-a-custom-dag-role) 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](/docs/astro/deployment-role-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](#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`](/docs/astro/deployment-role-reference#deployment) and [`deployment.deploys.create`](/docs/astro/deployment-role-reference#deployment-deploys).
7. Click **Create role**.
Your role is now available to assign at the Deployment level. See [Assign users and Teams to Deployments](#assign-users-and-teams-to-deployments) or [Create Deployment API tokens with custom Deployment roles](/docs/astro/deployment-api-tokens#create-a-deployment-api-token) 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 aren't hard-coded and exist only as templates.
* **Deployment Viewer**: This is similar to the [Airflow Viewer](https://airflow.apache.org/docs/apache-airflow-providers-fab/stable/auth-manager/access-control.html#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](https://airflow.apache.org/docs/apache-airflow-providers-fab/stable/auth-manager/access-control.html#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](https://airflow.apache.org/docs/apache-airflow-providers-fab/stable/auth-manager/access-control.html#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](/docs/astro/astro-mcp-server#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 doesn't work. See [Configure authentication](/docs/astro/astro-mcp-server#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 your Organization's access management settings:
1. In the Astro UI, go to **Settings** > **Access Management**.
2. Select the user or Team.
3. Click the **Deployments** tab, then click **+ Add Deployment** to add them to a Deployment, or **Edit Role** to change their role for an existing Deployment.
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, go to **Settings**, then in the **Access Management** section, click **Roles & Permissions**.
2. Click **Custom**, then click the name of the custom role you want to restrict.
3. Click the **Restricted Workspaces** tab.
4. In the **Edit Restricted Workspaces** panel, toggle **Workspace Restriction** to **On**.
5. Under **Restricted Workspaces**, select the checkboxes for the Workspaces you want to restrict the role to.
6. Click **Update Restricted Workspaces**.
1. In the Astro UI, click **Organization Settings** > **Access Management**.
2. 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**.