Your first pipeline

A pipeline lives at .hive/main.star in your repository. Starlark, not YAML.

Start small

Adopting Hive does not mean moving your whole build. Start with one cheap, uncontroversial step — a linter, a fast unit-test shard — leave your existing GitHub Actions workflows exactly where they are, and let the two run side by side. Nothing about Hive requires you to switch off what you already have, and running both for a while is the only way to compare them on your own repository.

Widen it once you trust it. A pipeline that does one thing well on every commit is worth more than a complete one that nobody has confidence in yet.

Watching a run

list_runs                       # recent runsget_run <run>                   # the task DAG, states, placementwait_for_run <run>              # block until it finishesexplain_failure <run>           # failing tasks: error + log tail, in one callget_task_logs <run> <task_key>  # one task's log

Run ids accept the #N number shown in the UI as well as the UUID. If a number is ambiguous across pipelines, narrow it with the project and pipeline.

explain_failure is the one to reach for first on a red run — it collapses "which task failed, why, and what did it print" into a single call.

What makes a run start

A push or pull-request webhook from a repository whose installation is bound to your tenant. If runs are not appearing, the problem is almost always the installation or the repo_url, not the pipeline file — see 03-github-app-and-projects.

A pipeline file that fails to evaluate is a different symptom: the run is created and fails immediately, rather than never appearing.