sync-plugins.yml

name: Sync InfluxDB 3 plugin documentation

on:
  schedule:
    # Run daily at 06:00 UTC.
    - cron: '0 6 * * *'
  workflow_dispatch:
    inputs:
      plugins:
        description: 'Plugin names to sync (comma-separated, or "all")'
        required: true
        default: 'all'

permissions:
  contents: write
  pull-requests: write

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

jobs:
  sync:
    runs-on: ubuntu-latest
    timeout-minutes: 20

    steps:
      # docs-v2 and the upstream checkout keep their historical layout:
      # docs_mapping.yaml resolves plugin READMEs at ../../../.ext relative to
      # helper-scripts/influxdb3-plugins, which is $GITHUB_WORKSPACE/.ext.
      - name: Checkout docs-v2
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          path: docs-v2
          # create-pull-request pushes with its own token, so the checkout
          # does not need to keep credentials in the worktree.
          persist-credentials: false

      - name: Checkout influxdb3_plugins
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          repository: influxdata/influxdb3_plugins
          path: .ext/influxdb3_plugins
          ref: main
          persist-credentials: false
          sparse-checkout: |
            influxdata/
            scripts/

      - name: Setup Node.js
        uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
        with:
          node-version-file: docs-v2/.nvmrc
          cache: 'yarn'
          cache-dependency-path: docs-v2/yarn.lock

      - name: Install dependencies
        working-directory: docs-v2
        run: CYPRESS_INSTALL_BINARY=0 yarn install --frozen-lockfile

      - name: Setup Python
        uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
        with:
          python-version: '3.x'

      # Informational only. The generator reports an unusable README as a
      # per-plugin skip, so one plugin failing template validation must not
      # block the other plugins from syncing.
      - name: Validate plugin READMEs
        working-directory: .ext/influxdb3_plugins
        env:
          PLUGINS: ${{ inputs.plugins }}
        run: |
          if [ "$PLUGINS" = "all" ]; then
            if validation_output=$(python scripts/validate_readme.py --errors-only 2>&1); then
              validation_status=0
            else
              validation_status=$?
            fi
          else
            if validation_output=$(python scripts/validate_readme.py --plugins "$PLUGINS" --errors-only 2>&1); then
              validation_status=0
            else
              validation_status=$?
            fi
          fi

          if [ "$validation_status" -eq 0 ]; then
            printf '%s\n' "$validation_output"
          else
            error_count=$(printf '%s\n' "$validation_output" | sed -nE 's/^Errors found: ([0-9]+)$/\1/p' | tail -n 1)
            echo "::group::README validation details"
            printf '%s\n' "$validation_output"
            echo "::endgroup::"

            if [ -n "$error_count" ]; then
              echo "::notice title=README validation::Found $error_count upstream README template errors; see the expanded step logs. Sync continues."
            else
              echo "::notice title=README validation::Validator exited with code $validation_status; see the expanded step logs. Sync continues."
            fi
          fi

      - name: Sync plugin documentation
        id: sync
        working-directory: docs-v2/helper-scripts/influxdb3-plugins
        env:
          PLUGINS: ${{ inputs.plugins }}
        run: node port_to_docs.js --plugin "$PLUGINS"

      # Runs on every sync, including a no-op run, so the coverage number
      # appears even when nothing changed. A regression past the committed
      # baseline fails the job in the last step, after the pull request is
      # opened -- the reviewer needs to see the gap, not just a red X.
      - name: Verify plugin coverage
        id: coverage
        continue-on-error: true
        working-directory: docs-v2/helper-scripts/influxdb3-plugins
        run: node verify-coverage.js

      - name: Check for changes
        id: changes
        working-directory: docs-v2
        run: |
          if [ -n "$(git status --porcelain)" ]; then
            echo "changed=true" >> "$GITHUB_OUTPUT"
          else
            echo "changed=false" >> "$GITHUB_OUTPUT"
            echo "No documentation changes. Skipping pull request."
          fi

      - name: Compose pull request body
        id: body
        if: steps.changes.outputs.changed == 'true'
        env:
          COVERAGE: ${{ steps.coverage.outputs.coverage_table }}
          NEEDS_ATTENTION: ${{ steps.sync.outputs.needs_attention }}
          SUMMARY: ${{ steps.sync.outputs.summary }}
        run: |
          BODY_FILE="$RUNNER_TEMP/pr-body.md"
          {
            if [ "$NEEDS_ATTENTION" = "true" ]; then
              cat <<'WARNING'
          > [!WARNING]
          > One or more plugins were skipped, pruned, newly scaffolded, or no longer
          > appear in the upstream registry index. Check the Status column
          > before merging.

          WARNING
            fi
            cat <<'INTRO'
          Automated sync from the `influxdata/influxdb3_plugins` registry index
          and plugin READMEs.

          ## Sync results

          INTRO
            printf '%s\n' "$SUMMARY"
            if [ -n "$COVERAGE" ]; then
              cat <<'COVERAGE_HEADING'

          ## Coverage

          Official plugins upstream, reconciled against what docs-v2 publishes.

          COVERAGE_HEADING
              printf '%s\n' "$COVERAGE"
            fi
            cat <<'LEGEND'

          ## What each status means

          - `updated` / `unchanged` — the generated region of the shared page.
          - `scaffolded` — a new product stub. Review its title, menu name, and
            tags; the generator cannot derive editorial tags from the registry.
          - `skipped` — the upstream checkout or a source README was unavailable.
          - `pruned` — a plugin in the registry has no source README; its shared
            page and product stubs were removed. Check for an upstream rename.
          - `removed` — a shared page whose plugin left the registry index.
            Resolve by hand: a rename and a delete are indistinguishable here,
            so the sync never deletes a published page.

          ## Ownership

          Structured facts live in `data/influxdb3_plugins.yml` and are fully
          generated. Prose between the `BEGIN` and `END GENERATED PLUGIN
          CONTENT` markers under
          `content/shared/influxdb3-plugins/plugins-library/official/` is
          regenerated every run; anything outside those markers is hand-owned
          and preserved. Product stubs under
          `content/influxdb3/{core,enterprise}/plugins/library/official/` are
          created once and never rewritten. A missing source README causes the
          sync to remove the shared page and both stubs.
          LEGEND
          } > "$BODY_FILE"
          echo "path=$BODY_FILE" >> "$GITHUB_OUTPUT"

      - name: Create or update pull request
        if: steps.changes.outputs.changed == 'true'
        uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v8
        with:
          path: docs-v2
          branch: sync/influxdb3-plugins
          commit-message: 'sync(plugins): update InfluxDB 3 plugin documentation'
          title: 'sync(plugins): update InfluxDB 3 plugin documentation'
          body-path: ${{ steps.body.outputs.path }}
          labels: |
            source:sync
            product:v3-monolith

      # Last, so a coverage regression still leaves a reviewable pull request
      # behind. A red job with no artifact tells a reviewer nothing.
      - name: Fail on a coverage regression
        if: steps.coverage.outcome == 'failure'
        run: |
          echo "Plugin coverage regressed past coverage-baseline.json." >&2
          echo "See the 'Verify plugin coverage' step for the plugins named." >&2
          exit 1