---
title: "Build"
description: "Pipelines that run a repository's tasks on every push, each in its own sandbox, and skip every task whose inputs haven't changed."
---

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

# Build

EZGH Build runs the tasks in a repository's `.ezgh/build.yaml` when the repository is pushed to.
Each task runs in its own [sandbox](/sandboxes), as one of your [bots](/iam/bots). **A task that
already ran on the same inputs never runs again**: its result is reused, and the pipeline says so.

- [Connect a repository](/build/connect) — EZGH Git or GitHub, the bot its tasks run as, and trusted refs.
- [The build file](/build/file) — Every key of .ezgh/build.yaml, and the rules the format keeps.
- [Skipping by content](/build/skipping) — What makes a task run again, and what doesn't.
- [Bots and trust](/build/bots-and-trust) — Which bot a task acts as, and how a bot trusts EZGH Build.
- [Secrets, buckets and clusters](/build/resources) — What a task gets when it names a resource.
- [Image builds](/build/image-builds) — Build a Dockerfile and push it to the project's registry.
- [Run locally](/build/run-locally) — Validate, plan and run your working tree with ezgh.
- [Agents](/build/agents) — The schema, Markdown pages and the hosted MCP server.

The Build API is at `https://build.ezghcloud.com`.

## A build file

```yaml
version: 1

trigger:
  branches: ["**"]
  tags: ["v*"]

tasks:
  deps:
    image: hub/library/golang:1.25
    inputs: [go.mod, go.sum]
    run: go mod download
    outputs: [/root/go/pkg/mod]

  vet:
    needs: [deps]
    image: hub/library/golang:1.25
    inputs: ["**/*.go", go.mod, go.sum]
    run: go vet ./...

  test:
    needs: [deps]
    image: hub/library/golang:1.25
    size: large
    inputs: ["**/*.go", go.mod, go.sum, "testdata/**"]
    warm: [/root/.cache/go-build]
    run: go test ./...

  image:
    needs: [vet, test]
    only: { branches: [main], tags: ["v*"] }
    bot: ci-builder
    inputs: [Dockerfile, "**/*.go", go.mod, go.sum]
    build:
      dockerfile: Dockerfile
      repository: team/app
      tags: [latest]

  rollout:
    needs: [image]
    only: { branches: [main] }
    image: hub/bitnami/kubectl:1.33
    bot: prod-deployer
    clusters: [production]
    cache: false
    inputs: []
    run: |
      kubectl set image deployment/app app="$EZGH_TASK_IMAGE_IMAGE"
      kubectl rollout status deployment/app --timeout=5m
```

A push that changes only `README.md` runs one task here, `rollout`: no other task lists that file in
its `inputs`, so `deps`, `vet`, `test` and `image` are reused.

## Connections, pipelines and tasks

| Resource | What it is |
| --- | --- |
| Connection (`bcn_…`) | A repository connected to a project, the bot its tasks run as, and its trusted refs |
| Pipeline (`bld_…`) | One run of the build file for a commit: `queued`, `running`, `succeeded`, `failed` or `cancelled` |
| Task (`btk_…`) | One task of a pipeline: `queued`, `running`, `succeeded`, `failed`, `cancelled`, `cached` (reused) or `skipped` (its `only` rule didn't match) |

A push to a branch or tag matched by the file's `trigger` starts a pipeline. Each task reports a
check on the commit, so its result shows on the commit and on its pull request. A new push to a
branch cancels that branch's pipelines that are still running, except on [trusted
refs](/build/skipping#trusted-refs), where every commit finishes.

## What it uses

Tasks run in sandboxes in the connection's project, at most 20 at once in an organization. They are
that project's Sandboxes usage, and cached results and built images are stored in its [Container
Registry](/registry). EZGH Build adds no charge of its own.

Source: https://docs.ezghcloud.com/build/index.mdx
