Shell task configuration

Configure a task's metadata as code

Task configuration defines the core metadata of an Airplane task in a .task.yaml or .task.json task definition file; this includes all information like the task name and parameters aside from the actual code that is executed when the task is run.

While tasks can be initially configured in the Airplane UI, defining tasks as code is advantageous because it allows you to reap the benefits of version control; you can 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.

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

The following is a complete reference of fields supported in .task.yaml or .task.json task definition file.

Standard fields

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

slug

string

REQUIRED

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 fewer than 50 characters long
Use only lowercase letters, numbers, and underscores
Start with a lowercase letter

name

string

REQUIRED

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

description

string

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

parameters

list

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

string

REQUIRED

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

string

REQUIRED

User-facing name for the parameter.

parameters.type

enum

REQUIRED

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

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

parameters.description

string

User-facing description of the parameter.

parameters.required

boolean

default: true

Whether the parameter is required.

parameters.default

string/number/boolean

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

parameters.options

list of string/number/boolean/object

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

string

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

requireRequests

boolean

default: false

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

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

allowSelfApprovals

boolean

default: true

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

restrictCallers

list of strings ("task" or "view")

default: []

The restrict callers execute rule disables direct execution of a task in the web UI and hides the task in the library. This rule can be configured to allow the task to be called from other tasks/runbooks and views.

timeout

number (in seconds)

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.

constraints

object

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.

schedules

object

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

string

REQUIRED

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

schedules.name

string

Name of the schedule.

schedules.description

string

Description of the schedule.

schedules.paramValues

object

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

resources

object

Mapping of resource aliases to resource slugs. Slugs for your resource can be found in the resource settings.

For more information on resource attachments, see resource attachments.

Example:

yaml
Copied
1
resources:
2
  db: prod_postgres_db

If you would like to use the resource slug as the alias for all resources passed into this task, you can also use a list shorthand:

yaml
Copied
1
resources:
2
  - prod_postgres_db
3
  - prod_rest_api

defaultRunPermissions

enum

default: task-viewers

Possible Values

task-viewersAnyone who can view the task can also view the run.

task-participantsCan only be viewed by those who execute, request, or approve the run.

Manage who can view new runs of this task.

Shell

shell

object

Marks the task as a Shell task.

Example:

yaml
Copied
1
shell:
2
  entrypoint: my_task.sh

shell.entrypoint

string

REQUIRED

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

object

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