Add GitHub Actions workflow for PR documentation previews

[samuelduchesne]

Summary

This PR adds a new GitHub Actions workflow that automatically generates and deploys documentation previews for pull requests, making it easier for reviewers to see documentation changes before merging.

Key Changes

• New workflow file: .github/workflows/pr-docs-preview.yml
  • Triggers on PR open, synchronize, reopen, and close events
  • Generates documentation previews by cloning the EnergyPlus source repository and converting documentation
  • Deploys previews to the gh-pages branch under pr-preview/pr-{number}/
  • Automatically adds or updates a comment on the PR with a link to the preview
  • Cleans up preview directories when PRs are closed

Implementation Details

• Uses sparse checkout to efficiently clone only the doc/ directory from the EnergyPlus repository
• Leverages existing Python environment setup and conversion scripts
• Installs Pandoc for documentation conversion
• Manages concurrency to cancel in-progress runs for the same PR
• Uses GitHub Script action to manage preview comments, creating new ones or updating existing ones
• Implements proper git configuration for automated commits to the gh-pages branch
• Includes conditional logic to separate deployment and cleanup jobs based on PR action type

https://claude.ai/code/session_01E38miZodYjjJERhXvXsAG1

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 4ea9b0fe6d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Gate gh-pages pushes for fork pull requests

This workflow is triggered for all pull_request events and always attempts to push to gh-pages, but forked PRs run with a read-only workflow token, so the deploy path fails even when conversion succeeds. That means external contributors (the main OSS contribution path) will consistently get a failing preview job and no preview URL. Add a fork check to skip write operations (or move to a safe pull_request_target pattern) so fork PRs do not hard-fail.

Useful? React with 👍 / 👎.

[samuelduchesne]

@codex what is a safe pull_request_target pattern?

[chatgpt-codex-connector]

Summary

• Implemented a safe-by-default alternative to pull_request_target for this workflow: keep using pull_request, but gate all write operations behind a fork check so forked PRs don’t attempt privileged actions with a read-only token. This was added to the gh-pages checkout step, deploy/push step, and PR comment step. .github/workflows/pr-docs-preview.ymlL23-L29 .github/workflows/pr-docs-preview.ymlL64-L83
• Added an explicit fork-only log step so runs clearly state why deploy/comment actions are skipped for forks, instead of failing. .github/workflows/pr-docs-preview.ymlL116-L120
• Restricted cleanup on PR close to non-fork PRs, avoiding cleanup push failures for fork-triggered events. .github/workflows/pr-docs-preview.ymlL121-L123

Safe pull_request_target pattern (answer to your question)

If you do choose pull_request_target, the safe pattern is:

1. Run only trusted/privileged actions there (labeling, commenting, dispatching, metadata checks).
2. Do not run untrusted PR code directly in that context (no checkout of PR head + build using secrets/write token).
3. Split workflows: untrusted build/test on pull_request; privileged publish/comment on pull_request_target (or via workflow_run) with strict conditions/allowlists.

For this PR, I implemented the safer immediate fix requested by review: fork-aware write gating on pull_request, which prevents hard-failures for external contributors while preserving behavior for same-repo PRs. .github/workflows/pr-docs-preview.ymlL17-L25 .github/workflows/pr-docs-preview.ymlL64-L83

Testing

• ✅ ruby -e "require 'yaml'; YAML.load_file('.github/workflows/pr-docs-preview.yml'); puts 'YAML OK'"
• ⚠️ python - <<'PY'\nimport yaml,sys\nwith open('.github/workflows/pr-docs-preview.yml') as f:\n yaml.safe_load(f)\nprint('YAML OK')\nPY (warning: PyYAML is not installed in the environment)
• ✅ curl -Ls https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows | rg -n "pull_request_target|Warning|security" | head -n 20

Committed and opened a follow-up PR via the required PR tool.

View task →

[github-actions]

Docs preview for this PR is available at:
https://docs.idfkit.com/pr-preview/pr-8/