update-docs-staging-x-repo.yml

# **What it does**: Triggers a repo disaptch event when pushing to a `docs-staging-x` branch
# or when a PR is labeled with `docs-staging-x`. The repo dispatch updates the corresponding
# docs-staging-x repo with the latest commit SHA, which triggers a deployment.
#
# Note: This does not work for docs-staging-{0/1} (review servers) updates to those are
# handled in the `update-review-servers-on-code-push.yml` workflow.
#
# **Why we have it**: Makes staging deployments easy
# **Who does it impact**: Anyone trying to deploy a staging branch, both Docs Content and Docs Engineering

name: Update docs-staging-x

on:
  push:
    branches:
      - 'docs-staging-[0-9]*'
  pull_request:
    types: [labeled]

permissions:
  contents: read

jobs:
  dispatch-sha:
    if: github.repository == 'github/docs-internal'
    runs-on: ubuntu-latest

    steps:
      # Needed because we call a composite action (Slack alert)
      - name: Checkout source repository
        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
        with:
          fetch-depth: 1 # Only need latest commit

      - name: Determine target staging repo
        id: determine_repo
        run: |
          # Determine the event type
          EVENT_TYPE="${{ github.event_name }}"

          SHOULD_DISPATCH="false"
          if [ "$EVENT_TYPE" = "push" ]; then
            # Triggered by a push event
            BRANCH_NAME=${GITHUB_REF#refs/heads/}
            echo "Triggered by push event on branch: $BRANCH_NAME"

            # Extract the staging number from branch name
            if [[ "$BRANCH_NAME" =~ ^docs-staging-([0-9]+)$ ]]; then
              STAGING_NUMBER="${BASH_REMATCH[1]}"
            else
              echo "Branch name does not match the required pattern docs-staging-X."
              exit 1
            fi

            # Get the commit SHA from the push event
            COMMIT_SHA="${GITHUB_SHA}"

          elif [ "$EVENT_TYPE" = "pull_request" ]; then
            # Triggered by a PR labeled event
            LABEL_NAME="${{ github.event.label.name }}"
            echo "Triggered by PR labeled event with label: $LABEL_NAME"

            if [[ "$LABEL_NAME" =~ ^docs-staging-([0-9]+)$ ]]; then
              STAGING_NUMBER="${BASH_REMATCH[1]}"
            else
              echo "Label does not match the required pattern docs-staging-X."
              # Do not dispatch if it doesn't match
              echo "should_dispatch=false" >> $GITHUB_OUTPUT
              exit 0
            fi

            # Get the commit SHA from the pull request head
            COMMIT_SHA="${{ github.event.pull_request.head.sha }}"

          else
            echo "Event type $EVENT_TYPE not supported."
            echo "should_dispatch=false" >> $GITHUB_OUTPUT
            exit 0
          fi

          echo "Staging Number: $STAGING_NUMBER"

          # Check if staging number is 0 or 1
          if [ "$STAGING_NUMBER" = "0" ] || [ "$STAGING_NUMBER" = "1" ]; then
            echo "Staging number $STAGING_NUMBER is reserved."
            echo "Review server repos are handled in the \`update-review-servers-on-code-push.yml\` repository."
            echo "should_dispatch=false" >> $GITHUB_OUTPUT
            exit 0
          fi

          TARGET_REPO="docs-staging-$STAGING_NUMBER"
          echo "Target Repository: $TARGET_REPO"
          SHOULD_DISPATCH="true"

          # Set outputs
          echo "target_repo=$TARGET_REPO" >> $GITHUB_OUTPUT
          echo "commit_sha=$COMMIT_SHA" >> $GITHUB_OUTPUT
          echo "should_dispatch=$SHOULD_DISPATCH" >> $GITHUB_OUTPUT

      - name: Dispatch repository dispatch event to staging repo
        if: steps.determine_repo.outputs.should_dispatch == 'true'
        env:
          REPO_DISPATCH_TOKEN: ${{ secrets.DOCS_BOT_PAT_WORKFLOW }}
          TARGET_OWNER: github
          TARGET_REPO: ${{ steps.determine_repo.outputs.target_repo }}
          EVENT_TYPE: update-sha
          SHA: ${{ steps.determine_repo.outputs.commit_sha }}
        run: |
          curl -X POST \
            -H "Accept: application/vnd.github.v3+json" \
            -H "Authorization: token $REPO_DISPATCH_TOKEN" \
            https://api.github.com/repos/$TARGET_OWNER/$TARGET_REPO/dispatches \
            -d "{\"event_type\":\"$EVENT_TYPE\",\"client_payload\":{\"SHA\":\"$SHA\"}}"

      - uses: ./.github/actions/slack-alert
        if: ${{ failure() && github.event_name != 'workflow_dispatch' }}
        with:
          slack_channel_id: ${{ secrets.DOCS_ALERTS_SLACK_CHANNEL_ID }}
          slack_token: ${{ secrets.SLACK_DOCS_BOT_TOKEN }}