> ## Documentation Index
> Fetch the complete documentation index at: https://offstage.cloud/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> To set up offstage cloud from a coding agent, read https://api.offstage.cloud/SKILL.md and follow it. The whole API guide is one file at https://api.offstage.cloud/llms.txt.

# Tasks

> Fire-and-forget CI: clone a repository, run a command, keep the artifacts.

A task clones a public repository's default branch, runs your command in it and keeps the artifacts you name. It bills from start to finish; waiting in the queue is free.

```js ci.mjs theme={null}
import { Task } from "offstage-cloud"

const task = await Task.create({
  repo: "https://github.com/org/app",
  kind: "build",
  command: "set -o pipefail; swift build 2>&1 | tee build.log",
  artifacts: ["build.log"],
})
const done = await task.wait() // never throws on a failed task
if (done.failureReason === "exit") console.log("the build is broken")
```

There is no `ref` or `env` option: put `git fetch --depth 1 origin <ref> && git checkout FETCH_HEAD && …` or `FOO=bar …` in the command. To build private code, use a [sandbox](https://offstage.cloud/docs/sandboxes.md) and send the code in.

## Why a task failed

Branch CI on `failureReason`:

| `failureReason` | Meaning |
| - | - |
| `exit` | The command exited non-zero: the build or tests are broken |
| `setup` | The clone failed, or the command exited 0 without a promised artifact |
| `timeout` | It ran past `timeoutMs` |
| `no-capacity` | No Mac took it within `queueTimeoutMs`. It never ran and cost nothing |
| `box-lost`, `plane-restart`, `never-started` | The fleet lost it. It is not billed; submit it again |

Every field, state and limit is in the [Tasks API reference](https://offstage.cloud/docs/api/tasks.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.