Permissions
Airplane's permissioning system allows for fine-grained, role-based access control for small and large organizations alike.
Groups
Groups
Permissions can be assigned directly to users or to groups of users. It's recommended that you
assign permissions to groups instead of users, so that new users simply have to be added to the
right group(s) instead of individual tasks, runbooks, etc.
For more information, see Groups.
Roles
Roles
By default, users on teams have limited permissions. Tasks and runbooks with permissions set to
"team access" can be viewed and executed by users.
For elevated permissions, groups can be assigned roles, and users can be added to groups to inherit
these permissions. Visit the group settings page and click the edit button on a group to set its
roles.
We support four roles at the group level: Restricted developer, Developer, User manager, and Team
admin. We support an additional role for service accounts: Deploy
Creator. Their capabilities are shown in the table below.
If you want tasks in an environment to be entirely controlled through Github or another CI/CD
solution, assign your developers the Restricted developer role in that environment. Restricted
developers cannot create new tasks or make changes to existing tasks.
No role | Restricted developer | Developer | User manager | Team admin | Deploy Creator | |
---|---|---|---|---|---|---|
Run tasks/runbooks set to "team access" | ✔ | ✔ | ✔ | ✔ | ✔ | |
Run any task/runbook | ✔ | ✔ | ✔ | |||
Update and move folders | ✔ | ✔ | ✔ | ✔ | ||
Update explicit permissions through the UI | ✔ | ✔ | ✔ | |||
Manage resources, API keys, and config vars | ✔ | ✔ | ✔ | |||
Access Studio | ✔ | ✔ | ✔ | |||
Create/update tasks, views, and runbooks | ✔ | ✔ | ✔ | |||
Manage git repos | ✔ | ✔ | ||||
Manage members and groups | ✔ | ✔ | ||||
Manage billing | ✔ | ✔ | ||||
Create and delete environments | ✔ |
Permissions across environments
Permissions across environments
Most entities in Airplane exist on a per-environment basis. This includes tasks, runbooks, config
variables, resources, and git repositories. Accordingly, Airplane allows explicit permissions on
those entities to be set on a per-environment basis, either in the UI or in code.
For groups, we allow having different roles for each environment.

The permissions associated with the Developer and Restricted developer roles only apply to the
environment the role is assigned to. For example, if a user is a Developer in the
stage
environment but has no role in the prod
environment, that user will only be able to update tasks
in stage
.On the other hand, the permissions associated with the User manager, Team admin, and Deploy Creator
roles are not tied to a specific environment. These roles can be assigned to a group when the
environment dropdown is set to
All
.See Roles for details.
Permissions in the UI
Permissions in the UI
You can configure granular permissions for a task, runbook, or view, or you can specify that
everyone on your team has access ("Team access").
When creating a task or runbook in the UI, click
Advanced
to configure granular permissions:
There are four roles that any user or group can be assigned for a task or runbook:
- Viewers can see task/runbook information, but can't request or execute tasks/runbooks.
- Requesters have all the permission of viewers, and can also request tasks/runbooks.
- Executers have all the permissions of requesters, and can also execute tasks/runbooks and others' requests.
- Admins have full access to the task/runbook, and can change configurations and permissions.
There are two roles that any user or group can be assigned for a view:
- Viewers can access the view, but cannot change view permissions.
- Admins can access the view and update permissions.
Users with a Role of
Team admin
, Developer
, or Restricted developer
can execute tasks and runbooks and access views regardless of their permissions.Once the task, runbook, or view is created, you can edit the permissions by clicking on the "Share"
button on the task, runbook, or view page.

Permissions in code
Permissions in code
You can configure task and view permissions in code in the task/view definition. When deployed, the
permissions in code will overwrite any permissions set in the UI and disable editing the permissions
in the UI.
You can either set permissions to be
"team_access"
for "Everyone at Airplane" permissions, or you
can set granular permissions:javascriptCopied1// list_orders.airplane.ts2export default airplane.task(3{4slug: "list_orders",5permissions: {6viewers: { groups: ["support"] },7executers: { users: ["jordan@airplane.dev"] },8},9},10async () => {...}11);
pythonCopied1# list_orders.py2@airplane.task(3permissions=airplane.ExplicitPermissions(4viewers=airplane.PermissionAssignees(groups=["support"]),5executers=airplane.PermissionAssignees(users=["jordan@airplane.dev"]),6)7)8def list_orders():9pass
In your task definition file (the file with extension
.task.yaml
):yamlCopied1# list_orders.task.yaml2permissions:3viewers:4groups:5- support6executers:7users:8- jordan@airplane.dev
javascriptCopied1// orders_dashboard.airplane.tsx2export default airplane.view(3{4slug: "orders_dashboard",5name: "Orders Dashboard",6permissions: {7viewers: { groups: ["support"] },8},9},10OrdersDashboard,11);
Sharing the same permissions across multiple tasks
Sharing the same permissions across multiple tasks
Since permissions are defined in code, you can share the same permissions across multiple tasks by
extracting the permissions object into a variable and referencing the variable.
javascriptCopied1// orders.airplane.ts2const PERMISSIONS = {3viewers: { groups: ["support"] },4executers: { users: ["jordan@airplane.dev"] },5};67export const listOrder = airplane.task(8{ slug: "list_orders", permissions: PERMISSIONS },9async () => {...}10);1112export const updateOrder = airplane.task(13{ slug: "update_order", permissions: PERMISSIONS },14async () => {...}15);
pythonCopied1# orders_airplane.py2PERMISSIONS = airplane.ExplicitPermissions(3viewers=airplane.PermissionAssignees(groups=["support"]),4executers=airplane.PermissionAssignees(users=["jordan@airplane.dev"]),5)67@airplane.task(permissions=PERMISSIONS)8def list_orders():9pass1011@airplane.task(permissions=PERMISSIONS)12def update_order():13pass
Permissions in different environments
Permissions in different environments
You can specify different permissions for different environments. For example, this can be useful if
you want to restrict access to a task in production but allow access in development.
javascriptCopied1// list_orders.airplane.ts2export default airplane.task(3{4slug: "list_orders",5permissions:6process.env.AIRPLANE_ENV_SLUG === "prod"7? {8viewers: {9groups: ["support"],10},11}12: "team_access",13},14async () => {...}15);
pythonCopied1# list_orders_airplane.py2@airplane.task(3permissions="team_access"4if os.environ.get("AIRPLANE_ENV_SLUG") == "prod"5else airplane.ExplicitPermissions(6viewers=airplane.PermissionAssignees(groups=["support"]),7),8)9def list_orders():10pass
In your task definition file (the file with extension
.task.yaml
):yamlCopied1# list_orders.task.yaml2permissions: team_access34environments:5prod:6permissions:7viewers:8groups:9- support
Read more about environment-based task configuration.
Run and session permissions
Run and session permissions
When executed, tasks and runbooks produce runs and sessions, respectively, and these can have
granular permissions assigned to determine who can view them.
The default permissions for a run can either be set to
task-viewers
or task-participants
:Task viewers
(default) Anyone who can view the task can also view the run. This means that if the task is team-accessible, the run can be viewed by anyone on the team. If the run has explicit permions enabled, allViewers
on the task can also view any run of the task.Task participants
Can only be viewed by those who execute, request, or approve the run. This is useful for runs that contain sensitive information, such as credentials, that should only be viewed by those who are directly involved in the run, and not by anyone who can view the task.
The default permissions for a runbook session is always
Session viewers
which has the same
behavior as Task viewers
.typescriptCopied1// list_orders.airplane.ts2export default airplane.task(3{4slug: "list_orders",5defaultRunPermissions: "task-participants",6},7async () => {...}8);
pythonCopied1# list_orders_airplane.py2@airplane.task(3default_run_permissions="task-participants",4)5def list_orders():6pass
In your task definition file (the file with extension
.task.yaml
):yamlCopied1# list_orders.task.yaml2defaultRunPermissions: task-participants
In the Advanced section of the task editor:

Once a run is created, its permissions can be edited from the sidepanel (e.g. select "Shared with
team"):

This is helpful if you have a locked-down task or runbook but want to selectively share the run or
session output with specific users or groups:

Requests and approvals
Requests and approvals
The Requester role allows for a balance between safety and access. For a given task or runbook,
a Requester can find that task in Airplane, fill out the parameters, but instead of running it
directly, the task/runbook must then get approved by an Executer or Admin. The "Requests" page in
the top navbar shows you a list of requests that you've sent as well as those from your teammates
that require your approval:

Next steps