---
title: "tasks in devlanes.yaml"
url: https://devlanes.run/docs/reference/config/project/tasks/
description: "Reference for the tasks key in devlanes.yaml."
---

# tasks in devlanes.yaml

A top-level key of [`devlanes.yaml`](/docs/reference/config/project/).

## `tasks`

Type: mapping of names to mappings.

One-shot commands such as installs, migrations and seeds, run by hand with `devlanes run <name>` or automatically at a lane event set with `when`. Tasks of the same event run in declaration order.

```yaml devlanes
tasks:
  migrate:
    run_script:
      file: apps/api/package.json
      name: migrate
    when: lane.start
```

### `tasks.<name>`

Type: mapping.

A one-shot command, run by hand with `devlanes run <name>` or automatically at a lane event set with `when`. Anything that ends by itself belongs here, not in `services`, where an exit counts as a failure.

```yaml devlanes
tasks:
  migrate:
    run_script:
      file: apps/api/package.json
      name: migrate
    when: lane.start
```

### `tasks.<name>.after`

Type: `services`.

Set to `services` to run a `lane.create` or `lane.start` task after the started services are ready instead of before them, for work that goes through the running app, such as seeding through its API.

Values:

- `services`: Run once every started service is ready; the task is skipped when one of them failed or the start timed out.

```yaml devlanes
tasks:
  migrate:
    after: services
```

### `tasks.<name>.confirm`

Type: string or an [expression](/docs/reference/expressions/).

Question asked before the task runs, for destructive tasks. Scripts and agents without a terminal must pass `--yes` to run it.

```yaml devlanes
tasks:
  migrate:
    confirm: Reset ${{ lane.db_name }} and re-seed it?
```

### `tasks.<name>.cwd`

Type: string or an [expression](/docs/reference/expressions/).

Working directory for `run`, relative to the project file's directory in the lane's worktree; defaults to that directory. Cannot be combined with `run_script`, which runs in the script file's directory.

```yaml devlanes
tasks:
  migrate:
    cwd: apps/api
```

### `tasks.<name>.env`

Type: mapping of names to strings, booleans, numbers or [expressions](/docs/reference/expressions/).

Variables for this task only, above `global_env`.

```yaml devlanes
tasks:
  migrate:
    env:
      API_URL: ${{ services.api.url }}
```

### `tasks.<name>.interactive`

Type: boolean or an [expression](/docs/reference/expressions/).

Give the task your terminal for input and output, for logins, prompts and TUIs. Interactive tasks only run by hand, so they cannot have `when`. Defaults to false.

```yaml devlanes
tasks:
  migrate:
    interactive: true
```

### `tasks.<name>.profiles`

Type: list of strings.

Run this task's `when` hook only while one of these profiles is active; `default` also matches a start without `--profile`. Runs by hand are not affected. Requires `when`.

```yaml devlanes
tasks:
  migrate:
    profiles:
      - default
      - backend
```

### `tasks.<name>.pty`

Type: boolean or an [expression](/docs/reference/expressions/).

Run the task in a pseudoterminal instead of plain pipes, for tools that only print colors or progress to a terminal. Defaults to the value of `interactive`.

```yaml devlanes
tasks:
  migrate:
    pty: true
```

### `tasks.<name>.run`

Type: string, list of strings or an [expression](/docs/reference/expressions/).

Command to run: a string runs through `/bin/sh -c` (pipes and multi-line scripts work), a list runs the program directly with those arguments. Use exactly one of `run`, `run_script` or `steps`. In a list, an item that is one `${{ }}` expression giving a number or `true`/`false` becomes its text, such as `--port` followed by `${{ self.port }}`.

```yaml devlanes
tasks:
  migrate:
    run: pnpm dev
```

### `tasks.<name>.run_script`

Type: mapping.

Script to run from a project file, as `{ file, name }`, such as `{ file: apps/api/package.json, name: migrate }`. It runs with that file's tool (the project's package manager for package.json) in the file's directory, and a missing script fails before anything starts. Prefer it to `run` for scripts that live in a file. Use exactly one of `run`, `run_script` or `steps`.

Takes the same keys as [`services.<name>.run_script`](/docs/reference/config/project/services/#services-name-run_script).

```yaml devlanes
tasks:
  migrate:
    run_script:
      file: apps/api/package.json
      name: dev
```

### `tasks.<name>.steps`

Type: list of strings.

Run these tasks and `infra.setup.<name>` or `infra.teardown.<name>` entries in order, stopping at the first failure, for jobs such as resetting a database. Each step runs whatever its own `when` says, and setup entries run again even when already done. Use instead of `run` or `run_script`.

```yaml devlanes
tasks:
  migrate:
    steps:
      - infra.teardown.database
      - infra.setup.database
      - migrate
      - seed
```

### `tasks.<name>.timeout`

Type: [duration](/docs/reference/config/#durations) or an [expression](/docs/reference/expressions/).

Longest the task may run. When it runs out, the task is stopped (SIGTERM, then SIGKILL after 10 seconds) and counts as failed; a failed task that runs before services fails the start. No limit by default.

```yaml devlanes
tasks:
  migrate:
    timeout: 15s
```

### `tasks.<name>.when`

Type: string.

Lane event that runs this task automatically. Without it the task runs only by hand with `devlanes run <name>` or as a step of another task.

Values:

- `lane.create`: Run on each start until it has succeeded once for the lane, then no longer automatically; for installs, code generation and a first seed.
- `lane.start`: Run on every start of the lane, before services unless `after: services` is set; for migrations and other steps that are safe to repeat.
- `lane.stop`: Run before the lane's processes stop when the whole lane stops: `devlanes stop` without unit names, `devlanes daemon stop` and `daemon restart`. Skipped when a signal (logout, system shutdown) stops the daemon.
- `lane.clean`: Run when the lane is cleaned (`devlanes lane clean`), after its processes stop and before `infra.teardown`.

```yaml devlanes
tasks:
  migrate:
    when: lane.create
```
