---
title: "Image builds"
description: "The build task, which builds a Dockerfile and pushes the image to the project's registry, and how the image is tagged."
---

> 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.

# Image builds

A task with `build` instead of `run` builds a Dockerfile and pushes the image to the project's
[Container Registry](/registry).

```yaml
tasks:
  image:
    bot: ci-builder
    inputs: [Dockerfile, "**/*.go", go.mod, go.sum]
    build:
      dockerfile: Dockerfile
      repository: team/app
      tags: [latest]
```

| Key | Meaning |
| --- | --- |
| `dockerfile` | The Dockerfile's path in the repository. When the task writes `inputs`, they must match it |
| `repository` | `<scope>/<image>` in the project's registry. It is created on the first push |
| `tags` | Extra literal tags |

A `build` task needs `bot`, which must be allowed to push to the repository. It takes no `image`,
`run`, `outputs` or `warm`. The task's `inputs` are the build context.

## Tags

| The pipeline is for | The image is tagged |
| --- | --- |
| A branch push | The commit SHA, and the task's `tags` |
| A tag push | The commit SHA, the tag's name, and the task's `tags` |
| A run from a working tree | `local-<pipeline ID>` only |

A Git tag's name becomes an image tag with every character other than letters, digits, `.`, `_` and
`-` replaced by `-`.

## Using the image

A task that needs a `build` task has `EZGH_TASK_<NAME>_IMAGE` set to the image by digest,
`host/repository@sha256:…`:

```yaml
  rollout:
    needs: [image]
    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"
```

## Base images

A Dockerfile's `FROM` pulls through the project's registry: Docker Hub images come through a
[pull-through cache rule](/registry/pull-through-cache). A base image behind a moving tag isn't in
the task's [key](/build/skipping#what-the-key-cant-see).

## When a build is reused

A `cached` build task builds nothing. This commit's tags are applied to the image it built before.

Source: https://docs.ezghcloud.com/build/image-builds/index.mdx
