Execute rules and constraints
Configure the execution behavior for a task or runbook.
Execute rules allow you to control task or runbook execution. For example, you can require
executions to go through requests or re-authentication, or constrain runs to specific agents.
Requests
By default, tasks and runbooks do not require requests and allow self-approvals. You can turn on
these options in the Advanced section of the task or runbook editor:

Requiring requests will disable schedules. Any existing schedules will be paused on the next
attempted execution.
Session and task behavior
If a task is run in a session, then it also considers the request on the session (if it exists) when
determining if the execute rules have been satisfied. In other words, if a session contains a task
that requires requests, and that session was requested, this satisfies the request requirement for
the task, and the task is executed as normal. Similarly, if the task disallows self-approvals and
the session request was not self-approved, the task is executed automatically.
However, if the request on the session does not satisfy the task's execute rules, or the session was
executed directly, then a request for that task will be automatically opened instead.
Re-authentication
Configuring a runbook or task to require re-authentication will prompt the user executing a runbook
or task or approving a request to authenticate again by signing in through Google or SSO. You can
turn on this option in the Advanced section of the task or runbook editor, under Execute Rules.

Require re-authentication is only enabled upon request. Please email us at
support@airplane.dev if you'd like access.
Requiring re-authentication will disable requests and task and runbook execution outside of the
Airplane UI. It will also disable schedules. Any existing schedules will be paused on the next
attempted execution.
Restrict callers
The restrict callers execute rule disables direct execution of a task in the web UI and hides the
task in the library.
This is useful for tasks that should only be called by other tasks/runbooks or views. For example,
you might have a task
delete_customer
that's used by another task, offboard_customer
. Enabling
the execute rule for delete_user
will ensure that users do not interact with it from the web UI.
But the task can still be executed indirectly through the offboard_customer
task.The restrict callers rule is available for tasks only. Runbooks do not have this option.
You can configure this through code:
typescriptCopied1import airplane from "airplane";23export default airplane.task(4{5slug: "delete_customer",6restrictCallers: ["task", "view"],7parameters: {8email: {9type: "shorttext",10name: "Customer email",11description: "The email address of the customer to delete.",12required: true,13},14},15},16async () => {17// ...18// delete_user_db deletes the user from the database.19// Users should never execute this task directly.20// It should only be called by the offboard_user task.21}22);
javascriptCopied1import airplane from "airplane";23export default airplane.task(4{5slug: "delete_customer",6restrictCallers: ["task", "view"],7parameters: {8email: {9type: "shorttext",10name: "Customer email",11description: "The email address of the customer to delete.",12required: true,13},14},15},16async () => {17// ...18// delete_user_db deletes the user from the database.19// Users should never execute this task directly.20// It should only be called by the offboard_user task.21}22);
pythonCopied1import airplane23@airplane.task(4description="Deletes a customer from the database.",5restrict_callers=["task", "view"],6)7def delete_customer():8"""9delete_customer deletes the user from the database.10Users should never execute this task directly.11"""12print("Deleting customer...")13# ...
For tasks with yaml definitions (such as SQL, REST, GraphQL, shell, and docker tasks), add the
restrictCallers
field to the task definition.
A shell task definition might look like this:yamlCopied1slug: test_yaml2name: test yaml34shell:5entrypoint: delete_customer.sh67# Disable direct execution and hide this task in the UI.8# This task can only be called by another task/runbook or view.9restrictCallers: ["task", "view"]
If you're configuring tasks from the UI, you can find this in the Advanced section:

Admins and developers can still see these tasks by searching for them or by toggling the "Show all
tasks button" in the top right of the library:

Tasks that are restricted will appear with a lock icon next to them.
To use this feature with views, @airplane/views must be
version 1.14.7 or higher.
Concurrency
If you need to prevent multiple tasks (or multiple copies of the same task) from executing at the
same time, you can set a concurrency key and limit.
You can configure this through code:
typescriptCopied1import airplane from "airplane";23export default airplane.task(4{5slug: "execute_nonconcurrent_operation",6concurrencyKey: "key1",7concurrencyLimit: 1,8},9async () => {10// ...11// execute_nonconcurrent_operation affects the database in a way12// such that we can't run two concurrent versions of it at once.13}14);
javascriptCopied1import airplane from "airplane";23export default airplane.task(4{5slug: "execute_nonconcurrent_operation",6concurrencyKey: "key1",7concurrencyLimit: 1,8},9async () => {10// ...11// execute_nonconcurrent_operation affects the database in a way12// that we can't run two concurrent versions of it at once.13}14);
pythonCopied1import airplane23@airplane.task(4description="Executes a sensitive operation that can't have multiple copies running at once.",5concurrency_key="key1",6concurrency_limit=1,7)8def execute_nonconcurrent_operation():9"""10execute_nonconcurrent_operation affects the database in a way11that we can't run two concurrent versions of it at once.12"""13print("Executing sensitive operation...")14# ...
For tasks with yaml definitions (such as SQL, REST, GraphQL, shell, and docker tasks), add the
concurrencyKey
and concurrencyLimit
field to the task definition.
A shell task definition might look like this:yamlCopied1slug: test_yaml2name: test yaml34shell:5entrypoint: execute_nonconcurrent_operation.sh67# Only one run with concurrency key set to "key1" can be active at any one time.8concurrencyKey: "key1"9concurrencyLimit: 1
If you're configuring tasks from the UI, you can find this in the Advanced section:

Runs with a concurrency key and limit set will not execute until the number of currently-active runs
with the same concurrency key are below the given limit. Note that this includes runs from the same
task, as well as runs from other environments.
For example, if a task has concurrency key set to
key1
and concurrency limit set to 1
, then it
will only start executing when there is no other active run with concurrency key also set to key1
.In most cases, the concurrency limit should be set to the default of 1. In the case where two tasks have the same concurrency key but different concurrency limits, the limits are checked on a per-task basis
For example, if
task1
has a limit of 1
and task2
has a limit of 2
, if there is one active
run with the given concurrency key, a run for task1
will wait to execute, but a run for task2
can start executing immediately.Run constraints
If you're self-hosting Airplane agents, you may want to control which agents
a run can be scheduled on. For example, you might have agents with different network configurations,
and a certain task must execute in a specific network.
With label constraints, runs will be scheduled only on agents with matching labels. Label
constraints can be specified on both tasks and runbooks.

Child run constraints
When executing another task or built-in, the child run
will inherit the constraints of the parent run that called it. In the case of overlapping labels,
the child run's constraints will take precedence over its inherited constraints.
If a runbook includes a task with conflicting constraints, the task block will fail to start.
Setting labels on self-hosted agents
Agent labels can be set with the
AP_LABELS
environment variable. Labels are key:value
string
pairs separated by spaces.Example:
AP_LABELS="aws-region:us-west-2 environment:prod"
To require that only runs with a specific constraint value run on a particular agent, prefix the
label with
required:
, e.g.: required:aws-region:us-west2
. Otherwise, unconstrained runs could
also be scheduled on the agent.For details on configuring agent labels for your specific environment, see
Agents.