The fact that the same workflow succeeds in quiltmc.org but fails in docs points to a repository-specific authentication or secret configuration issue rather than a problem with actions/download-artifact or the workflow YAML itself.

I agree, however, I have already tried all of your suggestions:

• COZY_PAT is an organisation secret and is available to all public repositories.
• The PAT itself is valid and has read/write permissions for repository contents and actions for both quiltmc.org and docs. The only thing I can possibly think of as being the problem is that I added the permission for docs after the token was stored as a secret, but that doesn't really make sense.
• publish-website.yaml is invoked in a workflow call, but one that I copied directly from quiltmc.org (which works). Secrets are inherited correctly, as far as I can tell.

That JSON response strongly suggests artifact exists and is accessible — so it's not an artifact/repo-side permission or visibility problem. The 401 is coming specifically from the credential the Action is sending.

The failure is almost certainly in the authentication credential being used by download-artifact. A 401 indicates GitHub rejected the credential.

Check, in order:

1. Is COZY_PAT actually resolving to a non-empty value at that step? Add a debug step before download-artifact:

   - name: Verify COZY_PAT
      run: |
        echo "Token length: ${#TOKEN}"
        curl -s \
          -H "Authorization: Bearer $TOKEN" \
          https://api.github.com/user | jq '.login'
      env:
        TOKEN: ${{ secrets.COZY_PAT }}

   If len=0, the secret isn't reaching this job (inheritance, secret mapping, or naming mismatch). https://docs.github.com/en/actions/how-tos/reuse-automations/reuse-workflows#passing-inputs-and-secrets-to-a-reusable-workflow

2. Trailing whitespace/newline in the secret value when it was pasted into org secrets — a corrupted token string is indistinguishable from "expired" and gives exactly Bad credentials.

3. Token expiry — fine-grained PATs can have short expirations; confirm it hasn't lapsed since you tested it manually.

Step 1 is the fastest way to know for certain whether the right secret is even arriving.

A PAT would only be necessary here when downloading an artifact from another repository or run

I have actually tried the built in secrets.GITHUB_TOKEN, which works correctly, but the PAT is used because in some cases the action does need to download an artefact from another run: in quiltmc.org there's a system that builds PR websites in a PR scope (build-pr-preview.yaml) and then publishes them in the repository scope so it can access the secrets needed for deployment (`publish-pr-preview.yaml), and that requires the workflow in the publishing run to download artefacts from the workflow in the building run.

That makes sense. I agree that run-id must remain for the workflow_run path because publish-pr-preview.yaml is downloading artifacts produced by a different workflow run.

However, those two runs are still in the same repository. actions/download-artifact requires a token for a different run, but that token does not have to be a PAT. The publishing run’s built-in github.token can access artifacts from another run in the same repository, provided it has actions: read. A PAT is only necessary if the artifact belongs to another repository.

I would therefore keep the reusable workflow generic but change it to:

jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      actions: read
      contents: read

    steps:
      - name: Download Website HTML
        uses: actions/download-artifact@v8
        with:
          name: html
          run-id: ${{ inputs.run-id }}
          github-token: ${{ github.token }}

I would also grant the permission on the reusable-workflow caller, since permissions can only stay the same or become more restrictive across nested reusable workflows:

publish-preview:
  uses: ./.github/workflows/publish-website.yaml
  needs: get-pr-number
  permissions:
    actions: read
    contents: read
  with:
    branch: preview-${{ needs.get-pr-number.outputs.pr-number }}
    run-id: ${{ github.event.workflow_run.id }}
  secrets: inherit

The same change can be made to the get-pr-number download.

Since replacing COZY_PAT with GITHUB_TOKEN succeeds, the artifact, repository and run ID are valid. It also means this is not fundamentally an artifact-sharing problem. The 401 is specifically associated with the PAT.

The validation step only proves that COZY_PAT is nonempty. To distinguish an invalid token from a repository-access problem, I would temporarily test the actual API calls:

- name: Validate Cozy PAT access
  env:
    GH_TOKEN: ${{ secrets.COZY_PAT }}
  run: |
    gh api user --jq .login
    gh api repos/${{ github.repository }} --jq .full_name
    gh api \
      repos/${{ github.repository }}/actions/runs/${{ inputs.run-id }}/artifacts \
      --jq .total_count

If gh api user returns 401, the stored token is expired, revoked, malformed or no longer valid, so it should be regenerated and the organization secret updated.

If the first request succeeds but one of the repository requests fails, check that the fine-grained PAT:

1. Uses QuiltMC as its resource owner.
2. Explicitly includes QuiltMC/docs.
3. Has Actions: read.
4. Is listed as active, rather than pending approval, under the organization’s personal access token settings.

Organization-secret repository access and PAT repository access are separate controls. Adding docs to the organization secret only makes the token value available to the workflow. It does not grant the token itself access to docs. Fine-grained PATs may also require organization approval before they can access organization resources.

For your current workflow_run design, I think the cleanest resolution is to use ${{ github.token }} with actions: read, retain the run-id, and reserve COZY_PAT for any future download that genuinely crosses repository boundaries. For a cross-repository download, also pass the target explicitly:

with:
  name: html
  repository: QuiltMC/target-repository
  run-id: ${{ inputs.run-id }}
  github-token: ${{ secrets.COZY_PAT }}