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:
typescript
Copied
1
import airplane from "airplane";
2


3
export default airplane.task(
4
  {
5
    slug: "delete_customer",
6
    restrictCallers: ["task", "view"],
7
    parameters: {
8
      email: {
9
        type: "shorttext",
10
        name: "Customer email",
11
        description: "The email address of the customer to delete.",
12
        required: true,
13
      },
14
    },
15
  },
16
  async () => {
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
);
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:
typescript
Copied
1
import airplane from "airplane";
2


3
export default airplane.task(
4
  {
5
    slug: "execute_nonconcurrent_operation",
6
    concurrencyKey: "key1",
7
    concurrencyLimit: 1,
8
  },
9
  async () => {
10
    // ...
11
    // execute_nonconcurrent_operation affects the database in a way
12
    // such that we can't run two concurrent versions of it at once.
13
  },
14
);
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.
Constraint values can be templated using JavaScript templates. If a constraint value resolves to null or undefined, the constraint will be ignored.
yaml
Copied
1
constraints:
2
  aws-region: "{{ params.region }}"
3
  # If region is "us-west-2" -> adds a "aws-region: us-west-2" constraint
4
  # If region is unset -> the `aws-region` constraint is ignored

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.
PrivacyTermsSupport