# Build Docker Image

> Trigger Docker image builds for Hyperlane agent, monorepo, or node service images. Use when the user wants to build new Docker images for a branch, commit, or tag.

- Skill: `hyperlane-xyz/build-docker-image` (Agent Skill)
- Install (CLI): `npx skillmds@latest add hyperlane-xyz/build-docker-image`
- Raw SKILL.md: https://api.skillmd.com/api/skills/hyperlane-xyz/build-docker-image/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: hyperlane-xyz (https://skillmd.com/u/hyperlane-xyz)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/hyperlane-xyz/build-docker-image

---


# Trigger Docker Image Builds

Build and publish Docker images to GHCR (`ghcr.io/hyperlane-xyz/*`).

## Workflows

| Workflow                   | Image(s)                  | Contents                                                                         |
| -------------------------- | ------------------------- | -------------------------------------------------------------------------------- |
| `rust-docker.yml`          | `hyperlane-agent`         | Rust relayer, validator, scraper                                                 |
| `monorepo-docker.yml`      | `hyperlane-monorepo`      | Full TS/Solidity monorepo                                                        |
| `node-services-docker.yml` | `hyperlane-node-services` | All TS node services (rebalancer, warp-monitor, ccip-server, keyfunder, relayer) |

## How to Trigger

Use `gh workflow run` with `--ref` to specify the branch, tag, or commit:

```bash
# Agent image (Rust)
gh workflow run rust-docker.yml --ref <branch>

# Monorepo image
gh workflow run monorepo-docker.yml --ref <branch>

# Node services (single unified image)
gh workflow run node-services-docker.yml --ref <branch>

# Include arm64 (multi-arch, slower)
gh workflow run rust-docker.yml --ref <branch> -f include_arm64=true
```

`--ref` defaults to `main` if omitted.

## After Triggering

1. Get the run URL:

   ```bash
   gh run list --workflow=<workflow>.yml --limit=1 --json url --jq '.[].url'
   ```

2. Get the run ID (wait a few seconds after triggering for the run to appear):

   ```bash
   gh run list --workflow=<workflow>.yml --limit=1 --json databaseId,status,createdAt --jq '.[0]'
   ```

3. Watch it:

   ```bash
   gh run watch <run-id>
   ```

4. The resulting image tag will be `<7-char-sha>-<YYYYMMDD>-<HHMMSS>`, e.g. `c558a9f-20260304-105241`.

5. Images are at `ghcr.io/hyperlane-xyz/<image-name>:<tag>`.

## Instructions

1. Ask the user which image(s) they want to build (agent, monorepo, node services, or all).
2. Ask which branch/ref (default: `main`).
3. Ask if arm64 is needed (default: no).
4. Trigger the workflow(s) with `gh workflow run`.
5. Fetch and report the run URL(s) using `gh run list`.
6. Optionally watch for completion if the user wants to wait.

## References

- To find existing images instead of building, use the `/find-docker-image` skill.
- See `docs/docker-image-policy.md` for the full Docker image policy.