JavaScript task configuration
airplane tasks init --from your_task_slug
to sync changes back to your code configuration.airplane tasks init --from=my_slug
and then copy/paste the code body into the newly created
.airplane.ts
file.Writing tasks
airplane.task(...)
,
which takes two parameters: the task configuration and the task implementation.typescriptCopied1// my_task.airplane.ts2import airplane from "airplane";34export default airplane.task(5// Task configuration6{7slug: "my_task",8name: "My Task",9description: "This is my task defined entirely in TypeScript!",10},11// Task implementation12async () => {13console.log("Hello World!");14}15);
Hello World!
when you run it.airplane.task(...)
will be discovered as tasks. You can even define multiple
tasks in the same file by using either the default or named exports for each of your tasks..airplane.js
,
.airplane.ts
, .airplane.jsx
, or .airplane.tsx
.typescriptCopied1// my_tasks.airplane.ts2import airplane from "airplane";34// Discoverable by Airplane5export default airplane.task(6{...},7async (params) => {...}8);910// Discoverable by Airplane11export const mySecondTask = airplane.task(12{...},13async (params) => {...}14);1516// NOT discoverable by Airplane because it isn't exported.17const mySecondTask = airplane.task(18{...},19async (params) => {...}20);
airplane deploy
, Airplane imports your task files to discover tasks. If you have any
code outside of the task implementation function (including code that is imported), this code will
also be executed. This allows you to define helper functions, constants, or other code that is
shared across tasks, but may also cause unexpected behavior if the code has side effects.typescriptCopied1// my_tasks.airplane.ts2import airplane from "airplane";34// You can share code between tasks by defining it outside of the task implementation function.5const getAirplaneTaskName = (slug) => `Airplane task ${slug}`;67// But be careful! This code will be executed when you run `airplane deploy`.8makeApiCall();910export default airplane.task(11{ slug: "my_task", name: getAirplaneTaskName("my_task") },12// Task implementation13async () => {14console.log("Hello World!");15}16);
Parameters
slug
and the value is the parameter configuration.typescriptCopied1parameters: {2id: {3type: "shorttext",4name: "The team's ID",5},6}
slug
and name
equal to the key.typescriptCopied1parameters: {2// The slug and name of the parater are "id".3id: "shorttext",4}
params
object.
If you are using TypeScript, The params
object is automatically typed based on your configuration!typescriptCopied1// my_task.airplane.ts2import airplane from "airplane";34export default airplane.task(5// Task configuration6{7slug: "my_task",8name: "My Task",9description: "This is my task defined entirely in JavaScript!",10parameters: {11// Required integer param with slug "my_int_param" and name "my_int_param"12my_int_param: "integer",13// Optional shorttext param with slug "my_optional_text_param" that defaults to "Hello!"14my_optional_text_param: {15type: "shorttext",16name: "My optional text param",17required: false,18default: "Hello!",19options: ["Hello!", "Good morning!"],20},21},22},23// The function takes a single argument, `params`, which is an object with the two params.24// e.g. { my_int_param: 3, my_optional_text_param: "Hello!" }25async (params) => {26console.log(`${params.my_optional_text_param}, ${params.my_int_param}`);27}28);
Examples
Attach a resource to a task and create a schedule
typescriptCopied1import airplane from "airplane";23export default airplane.task(4{5slug: "my_task",6parameters: {7text: "shorttext"8},9resources: {10// Attach the resource with slug "backend_db" under the alias "db"11db: "backend_db"12},13schedules: {14// Create a schedule for this task that runs at midnight each day15midnight_daily: {16cron: "0 0 * * *",17name: "Midnight daily",18description: "Runs at midnight each day",19paramValues: {20text: "text param value"21}22}23}24},25async (params) => {...}26);
Pass environment variables to a task and set label constraints for self-hosted agents
typescriptCopied1import airplane from "airplane";23export default airplane.task(4{5slug: "my_task",6envVars: {7// Pass an env var with a value8MY_ENV_VAR: "MY_ENV_VAR_VALUE",9// Pass an env var from a defined config var10MY_CONFIG_ENV_VAR: {config: "MY_CONFIG_ENV_VAR_VALUE"}11},12// Run only on agents with label "region:us-west-2"13constraints: {14region: "us-west-2"15}16},17async () => {...}18);
Require requests for task execution and set a custom timeout
typescriptCopied1import airplane from "airplane";23export default airplane.task(4{5slug: "my_task",6// Set a timeout of 200 seconds7timeout: 200,8// Require requests to execute9requireRequests: true,10allowSelfApprovals: false11},12async () => {...}13);
Reference
Task configuration
- Be fewer than 50 characters long.
- Use only lowercase letters, numbers and underscores.
- Start with a lowercase later.
A user-facing name for the task. This can be changed.
A user-facing description for the task. Supports markdown.
If true, a task must be requested before it can start executing. This disables direct execution, including schedules.
If true, a request can be approved by the requestor.
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.
AIRPLANE_RESOURCES
environment variable. For more information, see resource attachments.The implementation of the task.
Parameter configuration
A human-readable name that identifies this parameter.
A description that renders underneath the parameter.
Whether a non-empty value must be provided.
The initial value shown to users, also serves as the fallback if no value is provided.
shorttext
and longtext
parameters.label
can be provided for each option to override how these options are rendered in forms. Only valid for shorttext
, longtext
, sql
, integer
, float
, date
, and datetime
parameters.Schedule configuration
Name of the schedule.
Description of the schedule.
Map of param slug to value to pass to the task on each run.
YAML reference (deprecated)
airplane tasks init --from=my_slug
and then copy/paste the code body into the newly created
.airplane.ts
file.Standard fields
- Be fewer than 50 characters long
- Use only lowercase letters, numbers, and underscores
- Start with a lowercase letter
yamlCopied1parameters:2- slug: name3name: Name4type: shorttext5description: The user's name.6default: Alfred Pennyworth7required: false8options:9- Alfred Pennyworth10- Bruce Wayne11regex: "^[a-zA-Z ]+$"
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 |
label
and value
.yamlCopied1options:2- Alfred Pennyworth3- Bruce Wayne4- label: BW5value: Bruce Wayne
43200
(12 hours)yamlCopied1constraints:2aws-region: us-west-2
yamlCopied1schedules:2my_first_schedule:3cron: 0 0 * * *4name: My First Schedule5description: This is my first daily midnight UTC schedule!6paramValues:7my_first_param: my_first_param_value
yamlCopied1resources:2db: prod_postgres_db
yamlCopied1resources:2- prod_postgres_db3- prod_rest_api
Possible Values |
standard |
workflow |
standard
.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. |
JavaScript
yamlCopied1node:2entrypoint: my_task.ts3nodeVersion: "18"
.ts
or .js
file containing the logic for this task. This
can be absolute or relative to the location of the definition file.yamlCopied1entrypoint: my_folder/my_task.ts
Possible Values |
14 |
16 |
18 |
yamlCopied1envVars:2# From value3NODE_ENV:4value: production5# From config variable6MY_SECRET:7config: MY_SECRET_CONFIG_VAR