deploy.yml

# Reusable docs-site deploy: build the Docker image, push to GHCR, and deploy
# with Kamal to the oss-infrastructure server (behind a Cloudflare Tunnel +
# kamal-proxy). Every docs-kit site calls this so the deploy is defined ONCE.
#
# A site's own .github/workflows/deploy-docs.yml is a thin caller:
#
#   jobs:
#     deploy:
#       uses: mhenrixon/docs-kit/.github/workflows/deploy.yml@main
#       with:
#         image: mhenrixon/my-docs
#       secrets: inherit
#
# The image is built once (buildx, registry cache) and Kamal deploys it with
# --skip-push, so the image is never built twice.
name: Reusable docs deploy

on:
  workflow_call:
    inputs:
      image:
        description: >-
          GHCR image repo, e.g. mhenrixon/daisyui (no registry, no tag). Use the
          OWNER/REPO of the calling repo so the pushed package auto-links to the
          repo — then GITHUB_TOKEN can push AND pull it, no PAT needed. (A name
          that doesn't match the repo becomes an unlinked user-scoped package that
          GITHUB_TOKEN can't pull.)
        required: true
        type: string
      service:
        description: >-
          The Kamal service name (must equal `service:` in config/deploy.yml).
          Stamped as the `service` image LABEL so Kamal's validate_image passes
          on the --skip-push deploy — the image is built here (docker/build-push-action),
          not by `kamal build`, so Kamal never injects the label itself.
        required: true
        type: string
      ruby_version:
        description: "Ruby for the Kamal CLI."
        required: false
        default: "3.4"
        type: string
      working_directory:
        description: "The docs app dir holding config/deploy.yml (relative to repo root)."
        required: false
        default: "docs"
        type: string
      dockerfile:
        description: "Dockerfile path relative to repo root."
        required: false
        default: "docs/Dockerfile"
        type: string
      build_context:
        description: "Docker build context relative to repo root (repo root for a path-gem monorepo)."
        required: false
        default: "."
        type: string
      registry:
        description: "Container registry host."
        required: false
        default: "ghcr.io"
        type: string
    # These are marked required: false on purpose. Callers pass them with
    # `secrets: inherit`, and GitHub can't statically confirm an inherited secret
    # satisfies a `required: true` declaration — that combination produces a
    # startup_failure. They're still effectively required at runtime: the deploy
    # step fails fast (below) if DEPLOY_HOST/DEPLOY_DOMAIN are empty, and the SSH
    # agent step errors if SSH_PRIVATE_KEY is missing.
    secrets:
      SSH_PRIVATE_KEY:
        description: "Deploy key for the Kamal SSH user on the deploy host."
        required: false
      DEPLOY_HOST:
        description: "The deploy host (IP or DNS) — consumed by config/deploy.yml."
        required: false
      DEPLOY_DOMAIN:
        description: "The public host kamal-proxy routes — consumed by config/deploy.yml."
        required: false

concurrency:
  group: deploy-docs-${{ inputs.image }}
  cancel-in-progress: false

# Least privilege at the workflow level; each job widens only what it needs.
permissions:
  contents: read

jobs:
  build:
    runs-on: ubuntu-latest
    # Only the build job pushes to GHCR (docker/login-action + build-push-action).
    permissions:
      contents: read
      packages: write
    outputs:
      image_tag: ${{ steps.tag.outputs.image_tag }}
    steps:
      # persist-credentials: false — the build COPYs the repo root (incl .git,
      # kept for the gemspec's `git ls-files`) into the image, which is pushed to a
      # public ghcr package; a GITHUB_TOKEN persisted in .git/config must not ride
      # along into a published layer.
      - uses: actions/checkout@v4
        with:
          persist-credentials: false

      - name: Determine image tag
        id: tag
        env:
          EVENT_NAME: ${{ github.event_name }}
          RELEASE_TAG: ${{ github.event.release.tag_name }}
        run: |
          if [ "$EVENT_NAME" = "release" ]; then
            TAG="$RELEASE_TAG"
          else
            TAG="sha-$(git rev-parse --short HEAD)"
          fi
          echo "image_tag=$TAG" >> "$GITHUB_OUTPUT"
          echo "Building image tag: $TAG"

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Login to GitHub Container Registry
        uses: docker/login-action@v3
        with:
          registry: ${{ inputs.registry }}
          username: ${{ github.actor }}
          password: ${{ github.token }}

      - name: Build and push Docker image
        uses: docker/build-push-action@v6
        with:
          context: ${{ inputs.build_context }}
          file: ${{ inputs.dockerfile }}
          push: true
          tags: |
            ${{ inputs.registry }}/${{ inputs.image }}:${{ steps.tag.outputs.image_tag }}
            ${{ inputs.registry }}/${{ inputs.image }}:latest
          # Kamal's validate_image greps for this `service` label on the
          # --skip-push deploy; since the image is built here and not by
          # `kamal build`, we must stamp it ourselves.
          labels: |
            service=${{ inputs.service }}
          cache-from: type=registry,ref=${{ inputs.registry }}/${{ inputs.image }}:buildcache
          cache-to: type=registry,ref=${{ inputs.registry }}/${{ inputs.image }}:buildcache,mode=max

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment: docs
    # Pull-only (kamal deploy --skip-push); no image push, so packages: read.
    permissions:
      contents: read
      packages: read
    steps:
      - uses: actions/checkout@v4
        with:
          persist-credentials: false

      - uses: ruby/setup-ruby@v1
        with:
          ruby-version: ${{ inputs.ruby_version }}

      # Install the Kamal CLI directly so a consuming site doesn't need `kamal` in
      # its docs Gemfile. `kamal deploy` (not `bundle exec kamal`) then works for
      # every site regardless of its bundle.
      - name: Install Kamal
        run: gem install kamal

      - name: Setup SSH agent
        uses: webfactory/ssh-agent@v0.9.1
        with:
          ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}

      - name: Configure SSH for the deploy host
        env:
          DEPLOY_HOST: ${{ secrets.DEPLOY_HOST }}
        run: |
          mkdir -p ~/.ssh
          chmod 700 ~/.ssh
          # Disable host-key verification for the deploy host. Kamal uses net-ssh,
          # which raises HostKeyMismatch on any known_hosts conflict (e.g. after
          # the server is reprovisioned). net-ssh honors ~/.ssh/config, so this
          # turns verification off for this single known IP. Acceptable here: a
          # public read-only docs site reached over an authenticated deploy key.
          cat >> ~/.ssh/config <<EOF
          Host $DEPLOY_HOST
            StrictHostKeyChecking no
            UserKnownHostsFile /dev/null
          EOF
          chmod 600 ~/.ssh/config

      - name: Deploy with Kamal (image already pushed by the build job)
        working-directory: ${{ inputs.working_directory }}
        env:
          DEPLOY_HOST: ${{ secrets.DEPLOY_HOST }}
          DEPLOY_DOMAIN: ${{ secrets.DEPLOY_DOMAIN }}
          KAMAL_REGISTRY_PASSWORD: ${{ github.token }}
          IMAGE_TAG: ${{ needs.build.outputs.image_tag }}
        run: |
          # DEPLOY_HOST/DEPLOY_DOMAIN are `docs`-environment secrets that only
          # reach this job because the deploy job sets `environment: docs` AND the
          # caller sets `secrets: inherit`. If either is dropped they resolve to ""
          # with no error and Kamal would deploy against an empty host — fail fast.
          if [ -z "$DEPLOY_HOST" ] || [ -z "$DEPLOY_DOMAIN" ]; then
            echo "::error::DEPLOY_HOST/DEPLOY_DOMAIN empty — is the caller's 'secrets: inherit' set and does the deploy job keep 'environment: docs'?"
            exit 1
          fi
          kamal deploy \
            --skip-push \
            --version="$IMAGE_TAG"