Find Docker Images

Find existing Hyperlane Docker images on GHCR (ghcr.io/hyperlane-xyz/*).

Image Repositories

The hyperlane-node-services image is a unified image. Set SERVICE_NAME env var at runtime to select which service to run.

Tag Format

• Commit tags: <7-char-sha>-<YYYYMMDD>-<HHMMSS> (e.g. c558a9f-20260304-105241) — immutable, used in production
• Branch tags: main, my-feature-branch — mutable, overwritten on each build
• PR tags: pr-123 — ephemeral, cleaned up after 1 week

How to Find Images

Latest image for a branch

Use the mutable branch tag directly:

ghcr.io/hyperlane-xyz/hyperlane-agent:main

List all tags for an image

Query the OCI registry API (no auth needed for public images):

TOKEN=$(curl -s "https://ghcr.io/token?service=ghcr.io&scope=repository:hyperlane-xyz/<IMAGE>:pull" | jq -r .token)
curl -s -H "Authorization: Bearer $TOKEN" "https://ghcr.io/v2/hyperlane-xyz/<IMAGE>/tags/list" | jq '.tags'

Replace <IMAGE> with the image name (e.g. hyperlane-agent).

Find tag for a specific commit

Grep the tag list for a sha prefix:

TOKEN=$(curl -s "https://ghcr.io/token?service=ghcr.io&scope=repository:hyperlane-xyz/<IMAGE>:pull" | jq -r .token)
curl -s -H "Authorization: Bearer $TOKEN" "https://ghcr.io/v2/hyperlane-xyz/<IMAGE>/tags/list" | jq -r '.tags[]' | grep '<SHA_PREFIX>'

Find tag from latest workflow run

Look up the sha from the last successful build:

# Agent builds
gh run list --workflow=rust-docker.yml --branch=main --status=success --limit=1 --json headSha,createdAt --jq '.[0] | "\(.headSha[:7]) built \(.createdAt)"'

# Monorepo builds
gh run list --workflow=monorepo-docker.yml --branch=main --status=success --limit=1 --json headSha,createdAt --jq '.[0] | "\(.headSha[:7]) built \(.createdAt)"'

# Node service builds
gh run list --workflow=node-services-docker.yml --branch=main --status=success --limit=1 --json headSha,createdAt --jq '.[0] | "\(.headSha[:7]) built \(.createdAt)"'

Then match the sha against the GHCR tag list.

Check what's currently deployed in production

grep -E '(tag|Tag)' typescript/infra/config/docker.ts

Instructions

1. Determine what the user needs: latest for a branch, a specific commit, or what's deployed.
2. Use the appropriate method above to find the tag.
3. Return the full image reference: ghcr.io/hyperlane-xyz/<image>:<tag>.
4. If no image exists for their branch/commit, suggest using /build-docker-image to trigger one.

References

• To trigger a new build, use the /build-docker-image skill.
• See docs/docker-image-policy.md for the full Docker image policy.