openapi-sync.yml

name: OpenAPI sync

# Checks that openapi/v1.json still matches the document the API publishes. Once a week (and on
# demand) it compares the two by content. If they differ it opens, or comments on, ONE issue
# (label `openapi-drift`) with both versions, whether oasdiff finds a breaking change and in which
# direction, and a summary; when they match again it closes that issue. The run is red whenever the
# documents differ, so the scheduled run shows it too. Nothing is committed, pushed or merged: the
# vendored copy is the reference, and a person decides which side is behind.
#
# A document that cannot be fetched or parsed, or an oasdiff failure, is reported the same way, in
# an issue labelled `openapi-check-failed`, and the run is red.
on:
  schedule:
    - cron: "17 5 * * 1" # Mondays, 05:17 UTC
  workflow_dispatch:

permissions: {}

concurrency:
  group: openapi-sync
  cancel-in-progress: false

env:
  SPEC_URL: https://api.hodeishield.com/v1/openapi.json
  DRIFT_LABEL: openapi-drift
  FAILED_LABEL: openapi-check-failed
  OASDIFF_VERSION: "1.32.1"
  OASDIFF_SHA256: 7c8939fc49b75ee11fec66a5b83b37a2fca6aee109fed85013b1ba2ac2a1ee7f

jobs:
  check:
    name: check
    runs-on: ubuntu-latest
    timeout-minutes: 10
    permissions:
      contents: read
      issues: write # the report issue and its label
    env:
      GH_TOKEN: ${{ github.token }}
    steps:
      - name: Checkout dev
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          ref: dev
          persist-credentials: false

      - name: Test the issue script
        run: bash .github/scripts/openapi-drift-issue-test.sh

      - name: Compare with the published document
        id: compare
        run: |
          python3 .github/scripts/openapi-sync.py "$SPEC_URL" "$RUNNER_TEMP/sync" > "$RUNNER_TEMP/compare.out"
          cat "$RUNNER_TEMP/compare.out" >> "$GITHUB_OUTPUT"

      - name: Close the drift issue
        if: steps.compare.outputs.changed == 'false'
        run: >
          .github/scripts/openapi-drift-issue.sh resolve "$DRIFT_LABEL"
          "The published document and openapi/v1.json match again."

      # Pinned and checked against the checksum recorded above; bumped by hand in the periodic
      # dependency review (CONTRIBUTING.md).
      - name: Install oasdiff
        if: steps.compare.outputs.changed == 'true'
        run: |
          set -euo pipefail
          archive="oasdiff_${OASDIFF_VERSION}_linux_amd64.tar.gz"
          curl -sSfL -o "$RUNNER_TEMP/$archive" \
            "https://github.com/oasdiff/oasdiff/releases/download/v${OASDIFF_VERSION}/${archive}"
          echo "${OASDIFF_SHA256}  $RUNNER_TEMP/$archive" | sha256sum -c -
          tar -xzf "$RUNNER_TEMP/$archive" -C "$RUNNER_TEMP" oasdiff

      - name: Describe the difference
        if: steps.compare.outputs.changed == 'true'
        id: report
        run: |
          python3 .github/scripts/openapi-drift-report.py "$RUNNER_TEMP/oasdiff" "$RUNNER_TEMP/sync" \
            "$GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID" > "$RUNNER_TEMP/report.out"
          cat "$RUNNER_TEMP/report.out" >> "$GITHUB_OUTPUT"

      - name: Open or update the drift issue
        if: steps.compare.outputs.changed == 'true'
        env:
          PUBLISHED_SHA256: ${{ steps.report.outputs.published_sha256 }}
        run: >
          .github/scripts/openapi-drift-issue.sh report "$DRIFT_LABEL"
          "The published /v1 OpenAPI document differs from openapi/v1.json"
          "$RUNNER_TEMP/sync/body.md" "openapi-drift:$PUBLISHED_SHA256"

      - name: Fail on drift
        id: drift
        if: steps.compare.outputs.changed == 'true'
        run: |
          echo "The published document differs from openapi/v1.json; see the issue labelled $DRIFT_LABEL." >&2
          exit 1

      # Reached only when the check itself completed, with or without drift.
      - name: Close the report of an earlier failed check
        if: success() || steps.drift.conclusion == 'failure'
        run: .github/scripts/openapi-drift-issue.sh resolve "$FAILED_LABEL" "The check completed again."

      - name: Report a failed check
        if: failure() && steps.drift.conclusion != 'failure'
        run: |
          {
            echo "The weekly OpenAPI check could not complete, so it is unknown whether the published /v1 OpenAPI document and openapi/v1.json match."
            echo
            echo "The log of the run shows the step that failed: $GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID"
          } > "$RUNNER_TEMP/failed.md"
          .github/scripts/openapi-drift-issue.sh report "$FAILED_LABEL" \
            "The OpenAPI check could not complete" "$RUNNER_TEMP/failed.md"