# Command steps

> Your tests, builds and deploys, with context passed only as environment.

A command of yours: tests, a build, a deploy, a lint. It takes no terminal, it
runs in the card's own [checkout](/docs/worktrees), and it gives you back the
output as it came and an exit code.

## The form

| Field | What it is |
|---|---|
| **Name** | what the lane and the runs call it |
| **Command** | the line to run, for example `make test`. Required |
| **Give up after (seconds)** | left empty, it may take as long as it takes |

## Context arrives as environment, and only as environment

The command string is never built from the card. Everything the run knows is
set as an environment variable instead:

| Variable | What it holds |
|---|---|
| `DEVPIT_PROJECT` | the project's name |
| `DEVPIT_PROJECT_PATH` | the repository on disk |
| `DEVPIT_WORKTREE_PATH` | the card's checkout |
| `DEVPIT_BRANCH` | the branch that checkout is on |
| `DEVPIT_BASE_REF` | the commit the card's work started from |
| `DEVPIT_CARD` | the card's id |
| `DEVPIT_CARD_TITLE` | the card's title |

So write `git push origin "$DEVPIT_BRANCH"`, the way you would in a shell
script. The reason is not tidiness: a branch called `x; rm -rf /` becomes the
value of a variable rather than shell syntax, and that removes an entire class
of injection instead of trying to escape its way out of one.

Nothing is substituted into the command — a `{{branch}}` in it is not replaced
by anything — but the name is still read. A `{{key}}` naming something that is
not one of the keys above is refused when you save the step: *"`<key>` is not a
context key — the ones that exist are: …"*. Saving is when you are still
looking at what you typed; left to run time, the same typo surfaces two screens
away from the message.

## While it runs, and when it stops

Output streams onto the card as it arrives. A suite that takes twenty minutes
shows its first line at once, because buffering would make a working command
look exactly like a hung one for twenty minutes. A very long line arrives cut,
and a run that says more than devpit keeps ends with *"the rest was dropped"*.

**Give up after (seconds)** kills the run, which ends failed and says so:
*"killed after `<n>`s, the timeout this step declares"*. **Stop** on a running
run does the same by hand — it ends the shell and everything the shell started.

Secrets devpit handed out — a [profile's](/docs/profiles) environment, the
account token, the hook secret — are taken out of the output before it is
stored.

Exit code zero is still not a pass; see [Reading a check](/docs/checks).
