docs: add PR build validation, pin Hugo to 0.124.1, scope deploy permissions

[Copilot]

The docs workflow only ran on tag pushes, meaning Hugo build failures weren't caught until release. Additionally, hugo-version: 'latest' pulled Hugo v0.161.1 which is incompatible with Docsy v0.10.0, causing render failures.

Changes

• Add pull_request trigger — docs build now runs on every PR using the same checkout/setup/npm/Hugo steps as release builds
• Pin Hugo to 0.124.1 — fixes the render failure caused by Docsy incompatibility with latest (v0.161.1)
• Skip artifact upload on PRs — upload step gated with if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v'); PRs are validation-only
• Gate deploy job to tag pushes — same condition on the job itself; Pages deployment never runs for PRs
• Scope Pages permissions to deploy job — top-level reduced to contents: read; pages: write and id-token: write declared only on the deploy job

permissions:
  contents: read  # reduced from pages: write + id-token: write

jobs:
  build:
    # runs on PRs and tag pushes
    steps:
      - uses: peaceiris/actions-hugo@v3
        with:
          hugo-version: '0.124.1'  # was 'latest'
      - name: Upload artifact
        if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
        uses: actions/upload-pages-artifact@v3

  deploy:
    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
    permissions:
      pages: write
      id-token: write

Original prompt

Update the GitHub Actions workflow for docs publishing in the repository crossplane-contrib/function-hcl so that docs are built for every pull request using the same build steps as the release docs workflow, but without any publishing/deployment on PRs.

Context:

• The current workflow is .github/workflows/docs.yml.
• The existing workflow triggers on tag pushes (v*) and workflow_dispatch.
• The current build job performs checkout, Go setup, Hugo setup, Node setup, npm install, Pages configuration, and Hugo build.
• The current deploy job publishes to GitHub Pages.
• A recent failure showed the workflow was using hugo-version: 'latest', which pulled Hugo v0.161.1 and appears incompatible with the Docsy version in use. The workflow should pin Hugo to 0.124.1.

Required changes:

1. Update .github/workflows/docs.yml so the workflow also triggers on pull_request.
2. Keep a single shared docs build job that runs on both PRs and release tag pushes.
3. Ensure the deploy job only runs on tag pushes where github.ref starts with refs/tags/v.
4. Prevent publishing behavior on PRs.
5. Prefer not to grant Pages deployment permissions to PR runs unnecessarily:
   • Top-level workflow permissions should be reduced to contents: read.
   • The deploy job should declare pages: write and id-token: write permissions.
6. Skip actions/upload-pages-artifact on PR runs, since PRs are for validation only.
7. Pin Hugo in the workflow from latest to 0.124.1.

Acceptance criteria:

• A pull request build executes the same docs build pipeline (checkout, setup, npm install, Hugo build) as release docs builds.
• Pull request runs do not deploy to GitHub Pages.
• Tag pushes matching v* still build and deploy successfully.
• The workflow file remains clean and idiomatic GitHub Actions YAML.

Please create a pull request with these workflow changes against the main branch.

The following is the prior conversation context from the user's chat exploration (may be truncated):

User: Please find a solution for this failing job. Use the logs, job definition, and any referenced files where the failure occurred. Keep your response focused on the solution and include code suggestions when appropriate.

Assistant: The failure is in the docs build job, specifically the Hugo render step in the Pages workflow:

• Workflow: .github/workflows/docs.yml
• Failing step: Build with Hugo

The key error from the logs is:

• ERROR error building site: render: [en v1.0.0 guest] failed to render pages: render of "/404" failed
• failure originates in Docsy’s base template:
  github.com/google/docsy@v0.10.0/layouts/_default/baseof.html:4:7
• there is also a warning right before it:
  skipping template file ... td-render-heading.html: unrecognized render hook template

Most likely fix

This looks like a Hugo/Docsy compatibility issue, caused by the workflow using:

- name: Setup Hugo (Extended)
  uses: peaceiris/actions-hugo@v3
  with:
    hugo-version: 'latest'
    extended: true

Using latest pulled Hugo v0.161.1, which is likely too new for the pinned Docsy version (github.com/google/docsy@v0.10.0) referenced in the logs.

Recommended change

Pin Hugo to a version known to work with Docsy 0.10.x instead of using latest.

Update .github/workflows/docs.yml from:

- name: Setup Hugo (Extended)
  uses: peaceiris/actions-hugo@v3
  with:
    hugo-version: 'latest'
    extended: true

to something like:

- name: Setup Hugo (Extended)
  uses: peaceiris/actions-hugo@v3
  with:
    hugo-version: '0.124.1'
    extended: true

If your docs site was previously working on a different Hugo release, pin to that exact version instead.

Why this should solve it

• The logs show a template/render failure inside Docsy, not in your application code.
• The warning about td-render-heading.html being an “unrecognized render hook template” is a strong sign that the installed Hugo version and the theme/module version are out of sync.
• Since the workflow explicitly installs the latest Hugo, the build became vulnerable to upstream breaking template behavior.

Optional follow-up improvement

To avoid this recurring, keep both sides aligned:

• either pin Hugo in the workflow, or
• upgrade Docsy to a version compatible with newer Hugo releases

But the fastest fix for this job is to stop using latest and pin Hugo.

Patch suggestion

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index c35e547..XXXXXXX 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -35,7 +35,7 @@ jobs:
       - name: Setup Hugo (Extended)
         uses: ...

</details>



<!-- START COPILOT CODING AGENT SUFFIX -->

*This pull request was created from Copilot chat.*
>

[gotwarlost]

LGTM