docker.yml

name: Docker image

# The official self-host image, ghcr.io/cloudhal-dev/cloudhal (issue #143, docs/guides/self-host.md).
# Built from the npm release, never from the tree, so the image is exactly what npm users get.
# Three jobs, so that no release tag moves before the gates pass (#166):
# - `build` builds linux/amd64 + linux/arm64 with an SBOM and buildx provenance, pushes it under
#   the candidate tag `sha-<short>` only, then runs scripts/docker-smoke.ts on the amd64 image
#   (empty volume, health check, Studio's page, an anonymous `/mcp` call, the first owner through
#   the API, a publish, `site-build` twice) and Trivy, which fails the job on a CRITICAL
#   vulnerability with a fix;
# - `smoke-arm64` runs the same smoke test on the arm64 image, on GitHub's native arm64 runner
#   (free for public repositories; under QEMU a Node process and an Astro build take far longer
#   than the ten minutes that would be worth);
# - `tag` adds the release tags to the very digest that passed, with `imagetools create`, and then
#   writes the GitHub build attestation for it.
# Which tags `tag` adds:
# - release.yml calls this after a successful npm publish (`workflow_call` with the version), and
#   Actions › Docker image › Run workflow with a version re-publishes or backfills one. X.Y.Z
#   always; X.Y when the version is the highest patch of that minor among the repository's v*
#   tags; `latest` when it is the highest release of all. So a release started by hand still gets
#   `latest`, and a backfill of an older patch moves nothing backwards.
# - with no version (a dispatch without one, and nightly) `edge` is built from main's own packed
#   tarballs (scripts/pack-packages.ts) and tagged edge only, never latest;
# - a pull request that touches the image builds it for linux/amd64 without pushing and runs the
#   amd64 smoke test and the scan.
# Versions before 0.6.4 cannot pass the gates: the smoke test expects the first owner's setup
# token (#165), which 0.6.4 brought, and the image needs `--init-if-empty` (0.6.3). A backfill of
# 0.6.4–0.7.1 passes without the RFC-0043 status page: its CLI has no `cloudhal build --published`,
# so `site-build` (from this checkout) warns and builds the old way, and the smoke test skips its
# status-page checks.

on:
  workflow_call:
    inputs:
      version:
        description: Cloudhal version on npm, x.y.z
        type: string
        required: true
  workflow_dispatch:
    inputs:
      version:
        description: Cloudhal version on npm, x.y.z (empty builds edge from this ref)
        type: string
        required: false
        default: ""
  schedule:
    - cron: "41 3 * * *"
  pull_request:
    paths:
      - "deploy/docker/**"
      - ".github/workflows/docker.yml"
      - "scripts/docker-smoke.ts"
      - "scripts/pack-packages.ts"

permissions: {}

concurrency:
  group: docker-${{ github.event_name == 'pull_request' && github.ref || inputs.version || 'edge' }}
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}

env:
  IMAGE: ghcr.io/${{ github.repository_owner }}/cloudhal

jobs:
  build:
    name: ${{ inputs.version && format('Build {0}', inputs.version) || 'Build edge' }}
    runs-on: ubuntu-latest
    timeout-minutes: 90
    permissions:
      contents: read
      packages: write
    outputs:
      digest: ${{ steps.build.outputs.digest }}
    env:
      VERSION: ${{ inputs.version || '' }}
      PUSH: ${{ github.event_name != 'pull_request' }}
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false
      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
        with:
          node-version: 24
      # The compose file's Caddyfile, in the Caddy the compose file runs (a few seconds).
      - name: Validate the Caddyfile
        run: |
          docker run --rm \
            -e CLOUDHAL_BASE_URL=https://studio.example.com \
            -e CLOUDHAL_SITE_URL=https://www.example.com \
            -v "$PWD/deploy/docker/Caddyfile:/etc/caddy/Caddyfile:ro" \
            caddy:2.11 caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile
      - name: Check the version
        if: env.VERSION != ''
        run: |
          if ! [[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
            echo "::error::version must be x.y.z (got '$VERSION')"
            exit 1
          fi
      # The publish job tags after five minutes even when npm does not serve every package yet
      # (scripts/publish-ci.ts), and `npm install` in the image then fails with ETARGET (0.7.1:
      # @cloudhal/analytics appeared six minutes after its publish). Wait, up to 30 minutes, until
      # npm resolves every package of the release group at this version.
      - name: Wait until npm serves the release
        if: env.VERSION != ''
        run: |
          pkgs=$(jq -r '.fixed[0][]' .changeset/config.json)
          for attempt in $(seq 1 60); do
            missing=""
            for p in $pkgs; do
              [ "$(npm view "$p@$VERSION" version 2>/dev/null)" = "$VERSION" ] || missing="$missing $p"
            done
            if [ -z "$missing" ]; then
              echo "npm serves every package of the release group at $VERSION"
              exit 0
            fi
            echo "waiting for:$missing (attempt $attempt of 60)"
            sleep 30
          done
          echo "::error::npm does not serve$missing at $VERSION after 30 minutes"
          exit 1

      # edge: the packages of this ref, built and packed the way the release job packs them
      - if: env.VERSION == ''
        uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
      - if: env.VERSION == ''
        run: pnpm install --frozen-lockfile
      - if: env.VERSION == ''
        run: node scripts/pack-packages.ts deploy/docker/tarballs

      - if: env.PUSH == 'true'
        uses: docker/login-action@8aa5831fb8d48d8f76594c7ddde61ae58019f550 # v4.8.0
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      # The candidate tag only; the release tags come from the `tag` job once the gates pass.
      - id: meta
        uses: docker/metadata-action@dc802804100637a589fabce1cb79ff13a1411302 # v6.2.0
        with:
          images: ${{ env.IMAGE }}
          flavor: latest=false
          tags: type=sha,prefix=sha-
          labels: |
            org.opencontainers.image.title=Cloudhal
            org.opencontainers.image.description=Agent-native site platform: Studio, API and MCP server, self-hosted
            org.opencontainers.image.documentation=https://github.com/cloudhal-dev/cloudhal/blob/main/docs/guides/self-host.md
            org.opencontainers.image.vendor=Cloudhal
            org.opencontainers.image.version=${{ env.VERSION || 'edge' }}
      - if: env.PUSH == 'true'
        uses: docker/setup-qemu-action@99012661954931238ded8c8b007157a8430204e1 # v4.4.0
      - uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1
      - id: build
        uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7.4.0
        with:
          context: deploy/docker
          platforms: ${{ env.PUSH == 'true' && 'linux/amd64,linux/arm64' || 'linux/amd64' }}
          push: ${{ env.PUSH == 'true' }}
          load: ${{ env.PUSH != 'true' }}
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          build-args: CLOUDHAL_VERSION=${{ env.VERSION }}
          cache-from: type=gha
          cache-to: type=gha,mode=max
          # attestations need a registry push; a loaded local image takes none
          sbom: ${{ env.PUSH == 'true' }}
          provenance: ${{ env.PUSH == 'true' && 'mode=max' || 'false' }}

      - id: ref
        run: |
          if [ "$PUSH" = "true" ]; then echo "image=$IMAGE@$DIGEST" >> "$GITHUB_OUTPUT"
          else echo "image=$FIRST_TAG" >> "$GITHUB_OUTPUT"; fi
        env:
          DIGEST: ${{ steps.build.outputs.digest }}
          FIRST_TAG: ${{ fromJSON(steps.meta.outputs.json).tags[0] }}
      - name: Smoke test (linux/amd64)
        run: node scripts/docker-smoke.ts --image "$SMOKE_IMAGE"
        env:
          SMOKE_IMAGE: ${{ steps.ref.outputs.image }}
      - name: Trivy scan
        uses: aquasecurity/trivy-action@ed142fd0673e97e23eac54620cfb913e5ce36c25 # v0.36.0
        with:
          image-ref: ${{ steps.ref.outputs.image }}
          severity: CRITICAL
          ignore-unfixed: true
          exit-code: "1"
          format: table

  smoke-arm64:
    name: Smoke test (linux/arm64)
    needs: build
    if: github.event_name != 'pull_request'
    runs-on: ubuntu-24.04-arm
    timeout-minutes: 30
    permissions:
      contents: read
      packages: read
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false
      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
        with:
          node-version: 24
      - uses: docker/login-action@8aa5831fb8d48d8f76594c7ddde61ae58019f550 # v4.8.0
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - run: node scripts/docker-smoke.ts --image "$IMAGE@$DIGEST"
        env:
          DIGEST: ${{ needs.build.outputs.digest }}

  tag:
    name: ${{ inputs.version && format('Tag {0}', inputs.version) || 'Tag edge' }}
    needs: [build, smoke-arm64]
    if: github.event_name != 'pull_request'
    runs-on: ubuntu-latest
    timeout-minutes: 15
    permissions:
      contents: read
      packages: write
      id-token: write
      attestations: write
    env:
      VERSION: ${{ inputs.version || '' }}
      DIGEST: ${{ needs.build.outputs.digest }}
    steps:
      - uses: docker/login-action@8aa5831fb8d48d8f76594c7ddde61ae58019f550 # v4.8.0
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - id: tags
        name: Which tags this digest gets
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          set -euo pipefail
          if [ -z "$VERSION" ]; then
            tags="edge"
          else
            # Every released version: the repository's v* tags (release.yml pushes one per release)
            # plus this version itself, which has none yet when a release is finished by hand.
            # `grep` always matches at least this version, so the pipelines never come up empty.
            released=$( { gh api --paginate "repos/$GITHUB_REPOSITORY/git/matching-refs/tags/v" --jq '.[].ref' | sed 's#^refs/tags/v##'; echo "$VERSION"; } \
              | grep -E '^[0-9]+\.[0-9]+\.[0-9]+$' | sort -uV)
            minor="${VERSION%.*}"
            highest=$(printf '%s\n' "$released" | tail -n 1)
            highest_of_minor=$(printf '%s\n' "$released" | grep -E "^${minor//./\\.}\.[0-9]+$" | tail -n 1)
            tags="$VERSION"
            [ "$highest_of_minor" = "$VERSION" ] && tags="$tags $minor"
            [ "$highest" = "$VERSION" ] && tags="$tags latest"
          fi
          echo "tags=$tags" >> "$GITHUB_OUTPUT"
          echo "Tagging $IMAGE@$DIGEST as: $tags" | tee -a "$GITHUB_STEP_SUMMARY"
      - id: push
        name: Tag the digest that passed
        env:
          TAGS: ${{ steps.tags.outputs.tags }}
        run: |
          set -euo pipefail
          args=()
          for t in $TAGS; do args+=(--tag "$IMAGE:$t"); done
          # One source and no annotations: the index is copied as it is, so the digest stays the
          # one the smoke tests and Trivy saw. Read back and checked, and the attestation below
          # names what the tags really point at.
          docker buildx imagetools create "${args[@]}" "$IMAGE@$DIGEST"
          first="${TAGS%% *}"
          final=$(docker buildx imagetools inspect "$IMAGE:$first" --format '{{.Manifest.Digest}}')
          echo "digest=$final" >> "$GITHUB_OUTPUT"
          if [ "$final" != "$DIGEST" ]; then
            echo "::warning::$IMAGE:$first is $final, not the tested $DIGEST"
          fi
      - uses: actions/attest-build-provenance@4d101475d8b20a2381f78447822ac1eab6504dd8 # v4.2.2
        with:
          subject-name: ${{ env.IMAGE }}
          subject-digest: ${{ steps.push.outputs.digest }}
          push-to-registry: true