Task definition reference

Define tasks as code

The following is a complete reference of fields supported in task definitions. For guides to getting started, see:

What is a task definition?

Task definitions are files that define a task's metadata as code. Task definitions can be written in yaml or json and have the extension .task.yaml or .task.json.

Definining tasks as code is advantageous because it allows you to reap the benefits of version control: view the current state of a task and its history, subject tasks to the same code review and deploy mechanisms as the rest of your codebase, or roll back a task to a previous commit.

A task definition file is created when you initialize a task. Once the task is created, the best practice is to make further task updates directly to the task definition file rather than through the UI. This ensures that the task definition file always represents the source of truth.

If you do edit the task through the UI, you can rerun airplane init --from YOUR_TASK_SLUG path/to/defn.task.yaml to sync changes back to your task definition file.


Standard fields

The fields below apply to all task definitions, regardless of the type of task.

slugstringREQUIRED

A unique identifier that ties this definition file to a task in Airplane. This cannot be changed (a different slug will end up creating a new task).

Slugs must:

  • Be less than 50 characters long
  • Use only lowercase letters, numbers, and underscores
  • Start with a lowercase letter
namestringREQUIRED

User-facing name for the task. This can be changed.

descriptionstringoptional

User-facing description for the task. This can be changed.

parameterslistoptional

A list of parameters. Each parameter is a user-facing field to input data into the task.

Example:

yaml
Copied
1
parameters:
2
- slug: name
3
name: Name
4
type: shorttext
5
description: The user's name.
6
default: Alfred Pennyworth
7
required: false
8
options:
9
- Alfred Pennyworth
10
- Bruce Wayne
11
regex: "^[a-zA-Z ]+$"
parameters.slugstringREQUIRED

Unique identifier for the parameter. This is the identifier you'll use to interpolate parameters into arguments, pass them when calling from the CLI, etc.

parameters.namestringREQUIRED

User-facing name for the parameter.

parameters.typeenumREQUIRED
Possible Values
shorttextYour commonly used string input
longtextA string, but with a larger input box for users
sqlSimilar to Long Text inputs but offer SQL syntax highlighting
booleanPresented as on/off toggles
uploadAllows users to upload a file
Show more

The type of the parameter. See Parameter types for more information.

User-facing description of the parameter.

parameters.requiredbooleanoptional
Default: true

Whether the parameter is required.

parameters.defaultstring/number/booleanoptional

The default value of the parameter. The type depends on the type of the parameter.

parameters.optionslist of string/number/boolean/objectoptional

Constrains the value of parameter to a list of options.

The type depends on the type of the parameter.

You can optionally add a label to each option. Labels are shown to the user instead of the value. To add a label, the option should be an object with fields label and value.

Example:

yaml
Copied
1
options:
2
- Alfred Pennyworth
3
- Bruce Wayne
4
- label: BW
5
value: Bruce Wayne

For more information, see Select options.

parameters.regexstringoptional

Allows you to more dynamically control what values are permitted. For more information, see Regular expressions.

requireRequestsbooleanoptional
Default: false

If true, a task must be requested before it is executing. This disables direct execution, including schedules.

Requiring requests will disable schedules. Any existing schedules will be paused on the next attempted execution.

allowSelfApprovalsbooleanoptional
Default: true

If true, a request can be approved by the requestor.

timeoutnumber (in seconds)optional
Default: 3600 (1 hour)

Limits how long a task can run before it is automatically cancelled.

Maximum of 43200 (12 hours)

For more information, see timeouts.

constraintsobjectoptional

Restricts this task to run only on agents with matching labels.

Example:

yaml
Copied
1
constraints:
2
aws-region: us-west-2

For more information, see Run constraints.

schedulesobjectoptional

Mapping of unique identifiers to schedules that should be deployed with the task.

For more information, see Schedules.

Example:

yaml
Copied
1
schedules:
2
my_first_schedule:
3
cron: 0 0 * * *
4
name: My First Schedule
5
description: This is my first daily midnight UTC schedule!
6
paramValues:
7
my_first_param: my_first_param_value

The unique identifier is used to add, update and remove schedules as changes are made to the task definition file. Adding a new entry will create a new schedule, modifying an entry will update the schedule and removing an entry will pause the schedule.

The unique identifier must adhere to the slug format.

schedules.cronstringREQUIRED

Cron string of the schedule. To see acceptable formats, see Cron syntax.

schedules.namestringoptional

Name of the schedule.

schedules.descriptionstringoptional

Description of the schedule.

schedules.paramValuesobjectoptional

Map of param slugs and values to pass to the task on each run.


Node.js

nodeobjectoptional

Marks the task as a Node.js task.

Example:

yaml
Copied
1
node:
2
entrypoint: my_task.ts
3
nodeVersion: "16"
node.entrypointstringREQUIRED

The path to the .ts or .js file containing the logic for this task. This can be absolute or relative to the location of the definition file.

Examples:

yaml
Copied
1
entrypoint: my_folder/my_task.ts
node.nodeVersionenumREQUIRED
Possible Values
12
14
15
16

The Node.js version the task will be transpiled to.

node.envVarsobjectoptional

Environment variables that will be passed into the task.

Environment variables can be entered directly ("from value"), or you can reference Config variables ("from config variable"). Use config variables for secrets and/or values you want to share across multiple tasks.

Example:

yaml
Copied
1
envVars:
2
# From value
3
NODE_ENV:
4
value: production
5
# From config variable
6
MY_SECRET:
7
config: MY_SECRET_CONFIG_VAR

Python

pythonobjectoptional

Marks the task as a Python task.

Example:

yaml
Copied
1
python:
2
entrypoint: my_task.py
python.entrypointstringREQUIRED

The path to the .py file containing the logic for this task. This can be absolute or relative to the location of the definition file.

Examples:

yaml
Copied
1
entrypoint: my_folder/my_task.py
python.envVarsobjectoptional

Environment variables that will be passed into the task.

Environment variables can be entered directly ("from value"), or you can reference Config variables ("from config variable"). Use config variables for secrets and/or values you want to share across multiple tasks.

Example:

yaml
Copied
1
envVars:
2
# From value
3
API_ENDPOINT:
4
value: api.myco.dev/
5
# From config variable
6
MY_SECRET:
7
config: MY_SECRET_CONFIG_VAR

SQL

sqlobjectoptional

Marks the task as a SQL task.

Example:

yaml
Copied
1
sql:
2
resource: Prod DB
3
entrypoint: my_task.sql
sql.resourcestringREQUIRED

The name of an SQL resource. If you don't have an existing resource, visit the Resources settings page to add a new resource.

Example:

yaml
Copied
1
resource: Prod DB
sql.entrypointstringREQUIRED

The path to the .sql file containing the SQL query. This can be absolute or relative to the location of the definition file.

Examples:

yaml
Copied
1
entrypoint: my_folder/my_task.sql
sql.queryArgsobjectoptional

Query arguments that will be passed into the SQL query and referenced as :queryArgName.

Query arguments can either be hardcoded values or reference parameters as {{params.slug}}.

Example:

yaml
Copied
1
queryArgs:
2
name: John
3
# From parameter
4
id: "{{params.user_id}}"

These can be used in your SQL script:

sql
Copied
1
SELECT * FROM users WHERE name = :name AND id = :id;
sql.transactionModeenumoptional
Default: auto
Possible Values
auto
readOnly
readWrite
none

Specify the kind of transaction to use, or none for no transaction. The "auto" value here lets Airplane decide.

Example:

yaml
Copied
1
transactionMode: none
sql.configsobjectoptional

The configs attached to this task. See Config variables for more details on how to use config variables in your task.

Example:

yaml
Copied
1
configs:
2
- DEFAULT_SQL_PAGE_SIZE

Shell

shellobjectoptional

Marks the task as a Shell task.

Example:

yaml
Copied
1
shell:
2
entrypoint: my_task.sh
shell.entrypointstringREQUIRED

The path to the .sh file containing the shell script. This can be absolute or relative to the location of the definition file.

Examples:

yaml
Copied
1
entrypoint: my_folder/my_task.sh
shell.envVarsobjectoptional

Environment variables that will be passed into the task.

Environment variables can be entered directly ("from value"), or you can reference Config variables ("from config variable"). Use config variables for secrets and/or values you want to share across multiple tasks.

Example:

yaml
Copied
1
envVars:
2
# From value
3
ENV:
4
value: production
5
# From config variable
6
MY_SECRET:
7
config: MY_SECRET_CONFIG_VAR

REST

restobjectoptional

Marks the task as a REST task.

Examples:

POST

yaml
Copied
1
rest:
2
resource: Internal API
3
method: POST
4
path: "/users/{{params.user_id}}/update"
5
bodyType: json
6
body:
7
name: "{{params.user_name}}"

GET

yaml
Copied
1
rest:
2
resource: Internal API
3
method: GET
4
path: "/users/{{params.user_id}}"
5
urlParams:
6
page: 3
rest.resourcestringREQUIRED

The name of a REST API resource. If you don't have an existing resource, visit the Resources settings page to add a new resource.

rest.methodenumREQUIRED
Possible Values
GET
POST
PATCH
PUT
DELETE

The HTTP method to use.

rest.pathstringREQUIRED

The path to request. Your REST resource may specify a path prefix as part of its base URL, in which case this path is joined to it. Airplane recommends that this start with a leading slash.

rest.urlParamsobjectoptional

A key value map from param name to value.

Example:

yaml
Copied
1
page: 3
2
name: "{{params.user_name}}"
rest.bodyTypeenumoptional
Possible Values
json
raw
form-data
x-www-form-urlencoded

The type of body that this request should send.

rest.bodyobjectoptional

The body of the request for a request of method POST, PUT or PATCH. This field is required when bodytype is json or raw.

Example:

yaml
Copied
1
bodyType: json
2
body:
3
name: John
4
email: "{{params.user_email}}"
rest.formDataobjectoptional

The form data of the request for a request of method POST, PUT or PATCH. This field is required when bodytype is form-data or x-www-form-urlencoded.

Example:

yaml
Copied
1
bodyType: form-data
2
formData:
3
name: John
4
email: "{{params.user_email}}"
rest.configsobjectoptional

The configs attached to this task. See Config variables for more details on how to use config variables in your task.

Example:

yaml
Copied
1
configs:
2
- API_KEY

Docker

dockerobjectoptional

Marks the task as a Docker task.

Example:

yaml
Copied
1
docker:
2
image: ubuntu:21.04
3
command: "echo {{params.user_name}}"
docker.imagestringREQUIRED

The name of the image to use.

docker.commandstringoptional

The Docker command to run.

docker.entrypointstringoptional

A Docker entrypoint to override the default image entrypoint. If left unset, Airplane will use the default entrypoint of the image (if any).

Example:

yaml
Copied
1
entrypoint: bash