update-screenshots.yaml

name: Update All Screenshots
# Updates all screenshots on an existing PR, assuming permission has been given
# to maintainers to make edits.

on:
  workflow_dispatch:
    # Allows for manual triggering on PRs.  They should be reviewed first, to
    # avoid malicious code executing in the lab.
    inputs:
      pr:
        description: "A PR number to build and test in the lab."
        required: true

jobs:
  compute-sha:
    name: Compute SHA
    runs-on: ubuntu-latest
    outputs:
      SHA: ${{ steps.compute.outputs.SHA }}

    steps:
      - name: Compute SHA
        id: compute
        uses: shaka-project/shaka-github-tools/compute-sha@main
        with:
          ref: refs/pull/${{ inputs.pr }}/head

  set-pending-status:
    name: Set Pending Status
    needs: compute-sha
    runs-on: ubuntu-latest

    permissions:
      # "Write" to statuses to update commit status
      statuses: write

    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ needs.compute-sha.outputs.SHA }}
          persist-credentials: false

      - name: Set commit status to pending
        uses: shaka-project/shaka-github-tools/set-commit-status@main
        with:
          context: Update All Screenshots
          state: pending
          token: ${{ secrets.GITHUB_TOKEN }}

  run-lab-tests:
    name: Get Selenium Lab Screenshots
    needs: [set-pending-status]
    uses: ./.github/workflows/selenium-lab-tests.yaml

    permissions:
      # "Write" to statuses to update commit status, needed by nested jobs.
      statuses: write

    with:
      # Pass the pre-computed SHA directly to the nested workflow.
      # Do NOT pass "pr" and reinterpret it into a SHA in the nested workflow.
      sha: ${{ needs.compute-sha.outputs.SHA }}
      test_filter: layout
      ignore_test_status: true
      job_name_prefix: "Get Selenium Lab Screenshots / "

  commit-new-screenshots:
    name: Commit New Screenshots
    runs-on: ubuntu-latest
    needs: [compute-sha, run-lab-tests]
    # NOTE: NO PERMISSIONS ON THIS JOB.  It runs PR-author-controlled code from
    # the PR, and so must be untrusted!

    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ needs.compute-sha.outputs.SHA }}
          fetch-depth: 0
          persist-credentials: false

      - name: Get artifacts
        uses: actions/download-artifact@v4
        with:
          path: test/test/assets/screenshots/
          pattern: screenshots-*
          merge-multiple: true

      - name: Update screenshots
        run: |
          # NOTE: Steps of this could be influenced by the PR author, which is
          # why we run this job without any accessible tokens or special
          # permissions.

          # Install prerequisites.
          npm ci

          # Update the official screenshots for any that have visibly changed.
          # This is not a byte-for-byte comparison, but based on pixel diffs.
          ./build/updateScreenshots.py

          # Act as Shaka Bot.
          git config user.name "shaka-bot"
          git config user.email "shaka-bot@users.noreply.github.com"

          # Commit the changes to the screenshots only.  Ignore failure, in
          # case there are no changes.
          git add test/test/assets/screenshots/*/*.png || true
          git commit -m ':robot: Update all screenshots' || true

      - name: Cache Commits
        # Here we cache commits, made above in an untrusted job, to pull into a
        # separate, trusted job with permission to push to the repo.  The
        # untrusted job can't pollute the environment of the trusted job by,
        # say, modifying /usr/bin/gh.
        uses: actions/cache/save@v4
        with:
          path: .git/
          key: screenshot-commits-${{ needs.compute-sha.outputs.SHA }}

      - name: Debug
        uses: mxschmitt/action-tmate@v3.17
        with:
          limit-access-to-actor: true
        if: failure()

  update-pr:
    name: Update PR
    runs-on: ubuntu-latest
    needs: [compute-sha, commit-new-screenshots]

    # NOTE: No granular permissions here, because we use SHAKA_BOT_TOKEN
    # instead of the default token.  The action to push to the PR must be done
    # by an actor with permission, and the default GitHub token doesn't work.

    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ needs.compute-sha.outputs.SHA }}
          fetch-depth: 0
          persist-credentials: false

      - name: Restore Commits
        # Here we restore commits, made above in the above untrusted job, to
        # pull into this trusted job.  See comments above on "Cache Commits".
        uses: actions/cache/restore@v4
        with:
          path: .git/
          key: screenshot-commits-${{ needs.compute-sha.outputs.SHA }}

      - name: Update PR
        env:
          GH_TOKEN: ${{ secrets.SHAKA_BOT_TOKEN }}
        run: |
          # Update the PR.

          # Compute the destination for the push.  This uses the GitHub API
          # because this workflow is not triggered directly by a PR, so there
          # is no context variable that supplies these details.
          PR_API_URL="/repos/${{ github.repository }}/pulls/${{ inputs.pr }}"
          REMOTE=$(gh api $PR_API_URL | jq -r .head.repo.html_url)
          BRANCH=$(gh api $PR_API_URL | jq -r .head.ref)

          # Lean on $GH_TOKEN to authenticate the push.
          gh auth setup-git

          # If there were no changes, this will do nothing, but succeed.
          git push "$REMOTE" HEAD:"$BRANCH"

      - name: Debug
        uses: mxschmitt/action-tmate@v3.17
        with:
          limit-access-to-actor: true
        if: failure()

  set-final-status:
    name: Set Final Status
    runs-on: ubuntu-latest

    permissions:
      # "Write" to statuses to update commit status
      statuses: write

    needs: [compute-sha, run-lab-tests, update-pr]
    # Will run on success or failure, but not if the workflow is cancelled.
    if: ${{ success() || failure() }}
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ needs.compute-sha.outputs.SHA }}
          persist-credentials: false

      - name: Compute final status
        id: compute
        run: |
          # The final status must be one of: success, failure, error, pending.
          # However, the status from "result" from an earlier job is one of:
          # success, failure, cancelled, skipped.
          # We start by mapping those.
          LAB_TEST_RESULT=$(echo "${{ needs.run-lab-tests.result }}" \
              | sed -Ee 's/(cancelled|skipped)/error/')
          UPDATE_PR_RESULT=$(echo "${{ needs.update-pr.result }}" \
              | sed -Ee 's/(cancelled|skipped)/error/')

          if [[ "$LAB_TEST_RESULT" == "success" ]]; then
            # If run-lab-tests succeeded, use the status of update-pr, which
            # comes after that.  If that is blank, default to "error".
            echo "status=${UPDATE_PR_RESULT:-error}" >> $GITHUB_OUTPUT
          else
            # If run-lab-tests failed, use that.  If that is blank, default to
            # "error".
            echo "status=${LAB_TEST_RESULT:-error}" >> $GITHUB_OUTPUT
          fi

      - name: Report final status
        uses: shaka-project/shaka-github-tools/set-commit-status@main
        with:
          context: Update All Screenshots
          state: ${{ steps.compute.outputs.status }}
          token: ${{ secrets.GITHUB_TOKEN }}