(PUP-12055) Build references on commit to main

When a commit is pushed to main, build all of the references, including man
pages. If the only changes are due to SHA and dates, then do nothing. Otherwise,
commit all of the references and man pages.

The action is only triggered when a commit is pushed to main, but not on pull
requests so that we don't have to worry about untrusted inputs.

The action is only triggered when the repo owner is puppetlabs, so it won't
trigger on forks.

The action uses full SHAs for the pandoc and add-and-commit actions.

If changes are detected, the action creates a commit whose author is GitHub
Actions <[email protected]> with message:

    Update references [no-promote]

And pushes the commit to the main branch. It uses the repository's GITHUB_TOKEN
to accomplish this. We don't need to worry about recursive workflow runs[1]:

    When you use the repository's GITHUB_TOKEN to perform tasks, events
    triggered by the GITHUB_TOKEN ... will not create a new workflow run. This
    prevents you from accidentally creating recursive workflow runs.

[1] https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/triggering-a-workflow

Author: joshcooper

.github/workflows/references.yaml

@@ -0,0 +1,50 @@
+---
+name: Generate References
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+
+jobs:
+  generate_references:
+    if: ${{ github.repository_owner == 'puppetlabs' }}
+    runs-on: ubuntu-latest
+    name: Generate References
+    env:
+      BUNDLE_WITH: "documentation"
+      BUNDLE_WITHOUT: "features packaging"
+    steps:
+      - name: Checkout current PR
+        uses: actions/checkout@v4
+
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: 3.2
+          bundler-cache: true
+
+      - name: Setup Pandoc
+        uses: pandoc/actions/setup@d940685d5968400c91029147adbd612deb7696b0
+        with:
+          version: 3.1.8
+
+      - name: Generate References
+        id: generate-references
+        run: |
+          bundle exec rake references:all
+          git --no-pager diff --exit-code --ignore-matching-lines='This page was generated from the Puppet source' --ignore-matching-lines='built_from_commit:' man references || echo 'commit=true' >> "$GITHUB_OUTPUT" 
+
+      - name: Commit and Push
+        if: ${{ steps.generate-references.outputs.commit == 'true' }}
+        uses: EndBug/add-and-commit@a94899bca583c204427a224a7af87c02f9b325d5
+        with:
+          author_name: GitHub Actions
+          author_email: [email protected]
+          message: 'Update references [no-promote]'
+          add: 'man references'
+          push: true
+