docs.yml

name: Build, Scan & Publish Docs

on:
  push:
    branches: [main]
    paths:
      - "docs/**"
      - ".github/workflows/docs.yml"
      - ".trivyignore.yaml"
      - ".nvmrc"
  schedule:
    - cron: "47 4 * * 1"
  workflow_dispatch:

concurrency:
  group: docs-image-${{ github.ref }}
  cancel-in-progress: false

permissions:
  contents: read

env:
  IMAGE: ghcr.io/openmapx/docs

jobs:
  docs:
    runs-on: ubuntu-latest
    timeout-minutes: 30
    permissions:
      contents: read
      packages: write
      security-events: write
    steps:
      - name: Select trusted docs source
        id: source
        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
        with:
          script: |
            if (!["push", "schedule", "workflow_dispatch"].includes(context.eventName) ||
                context.ref !== "refs/heads/main") {
              throw new Error("Docs publication requires trusted main");
            }
            // Serial main runs select current source before building. A queued
            // older run cannot roll docs back after a newer main revision.
            const { data: main } = await github.rest.git.getRef({...context.repo, ref: "heads/main"});
            const sha = main.object.sha;
            core.setOutput("sha", sha);
            core.setOutput("release", `${sha}-${context.runId}-${process.env.GITHUB_RUN_ATTEMPT}`);

      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          ref: ${{ steps.source.outputs.sha }}
          persist-credentials: false
      - name: Set up Docker Buildx
        id: buildx
        continue-on-error: true
        uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1
      - name: Retry Docker Buildx setup
        if: steps.buildx.outcome == 'failure'
        uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1
      - name: Log in to the candidate registry
        uses: docker/login-action@81c6f93d4bc991e510b342a00b419b3bb4efc5c6 # v4.7.0
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ github.token }}
      - name: Build docs candidate
        id: build
        uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7.4.0
        with:
          context: docs
          file: docs/Dockerfile
          platforms: linux/amd64
          pull: true
          no-cache: ${{ github.event_name == 'schedule' || vars.OPENMAPX_FORCE_DOCS_REBUILD == 'true' }}
          outputs: ${{ format('type=image,name={0},push-by-digest=true,name-canonical=true,push=true', env.IMAGE) }}
          labels: |
            org.opencontainers.image.revision=${{ steps.source.outputs.sha }}
            org.opencontainers.image.source=${{ github.server_url }}/${{ github.repository }}
          cache-from: type=gha,scope=docs
          cache-to: type=gha,mode=max,scope=docs
          provenance: mode=max
          sbom: true
      - name: Audit docs candidate
        uses: aquasecurity/trivy-action@ed142fd0673e97e23eac54620cfb913e5ce36c25 # v0.36.0
        with:
          version: v0.76.1
          image-ref: ${{ env.IMAGE }}@${{ steps.build.outputs.digest }}
          format: sarif
          output: trivy-docs.sarif
          scanners: vuln
          vuln-type: os,library
          severity: CRITICAL,HIGH
          limit-severities-for-sarif: true
          ignore-unfixed: "false"
          exit-code: "0"
      - name: Gate docs candidate
        uses: aquasecurity/trivy-action@ed142fd0673e97e23eac54620cfb913e5ce36c25 # v0.36.0
        with:
          version: v0.76.1
          image-ref: ${{ env.IMAGE }}@${{ steps.build.outputs.digest }}
          format: table
          scanners: vuln
          vuln-type: os,library
          severity: CRITICAL,HIGH
          ignore-unfixed: "true"
          trivyignores: .trivyignore.yaml
          exit-code: "1"
      - name: Upload docs scan report
        if: always() && (github.event.repository.visibility == 'public' || vars.ENABLE_CODE_SCANNING == 'true')
        uses: github/codeql-action/upload-sarif@9b3254085494b55a0f7c4c2b3d2d52cc712ce370 # v4.39.1
        with:
          sarif_file: trivy-docs.sarif
          category: trivy-docs
      - name: Publish and verify docs aliases
        env:
          DIGEST: ${{ steps.build.outputs.digest }}
          RELEASE_SHA: ${{ steps.source.outputs.sha }}
          RELEASE_ID: ${{ steps.source.outputs.release }}
        run: |
          if [[ ! "$DIGEST" =~ ^sha256:[a-f0-9]{64}$ ]]; then
            echo "Invalid scanned docs digest" >&2
            exit 1
          fi
          for tag in "$RELEASE_ID" "$RELEASE_SHA" latest; do
            docker buildx imagetools create --prefer-index=false --tag "${IMAGE}:${tag}" "${IMAGE}@${DIGEST}"
            actual=$(docker buildx imagetools inspect "${IMAGE}:${tag}" --format '{{.Manifest.Digest}}')
            if [ "$actual" != "$DIGEST" ]; then
              echo "Published docs digest mismatch for ${tag}" >&2
              exit 1
            fi
          done
          printf '%s\n' "### Published documentation" "" "Source revision: ${RELEASE_SHA}" "" "Image: ${IMAGE}@${DIGEST}" "" "Rollback tag: ${IMAGE}:${RELEASE_ID}" >> "$GITHUB_STEP_SUMMARY"