Skip to content

ci(docs): always trigger docs workflow on PRs; move filtering into workflow#1544

Merged
thinkall merged 3 commits into
mainfrom
thinkall/docs-workflow-always-trigger-on-pr
May 9, 2026
Merged

ci(docs): always trigger docs workflow on PRs; move filtering into workflow#1544
thinkall merged 3 commits into
mainfrom
thinkall/docs-workflow-always-trigger-on-pr

Conversation

@thinkall
Copy link
Copy Markdown
Collaborator

@thinkall thinkall commented May 9, 2026

Why

Today the docs workflow uses trigger-level paths filters. When a PR doesn't touch any of those paths, GitHub never starts the workflow, so the docs check is reported as expected but not run — which can leave required-status-check rules waiting indefinitely and makes branch-protection harder to manage.

What

  • Drop the paths filters from both the pull_request and push triggers so the workflow always starts on PRs (and on pushes to main) and reliably reports a check status.
  • Add a changes job that uses dorny/paths-filter@v3 to detect doc-related changes inside the workflow, with recursive globs:
    • flaml/**
    • website/**
    • .github/workflows/deploy-website.yml
  • Gate the existing checks and gh-release jobs on needs.changes.outputs.docs so the heavy build/deploy steps are still skipped when nothing relevant changed (preserving today's compute behavior).
  • workflow_dispatch (and merge_group for checks) can still force a run regardless of the filter.

The previous flaml/* / website/* patterns only matched files in the top of those directories — switching to ** ensures changes anywhere in the tree are picked up.

Behavior matrix

Event changes checks gh-release
pull_request always runs only if doc files changed never
push to main always never runs only if doc files changed
workflow_dispatch always always always
merge_group always always runs only if doc files changed

- Drop the `paths` trigger filters so the docs workflow always runs
  on pull requests (and pushes) and reliably reports its check status.
- Add a `changes` job using dorny/paths-filter@v3 to detect doc-related
  changes inside the workflow with recursive globs (`flaml/**`,
  `website/**`, `.github/workflows/deploy-website.yml`).
- Gate `checks` and `gh-release` on the filter output so the heavy
  steps are skipped when no doc-related files changed, while
  `workflow_dispatch` (and `merge_group` for `checks`) can still
  force a run.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copy link
Copy Markdown

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adjusts the docs GitHub Actions workflow so it always triggers on PRs/pushes (avoiding “expected but not run” required-check deadlocks) while keeping expensive docs build/deploy steps conditional on doc-related file changes detected inside the workflow.

Changes:

  • Removed trigger-level paths filters so the workflow always starts on pull_request and push to main.
  • Added a changes job using dorny/paths-filter@v3 with recursive globs to detect doc-related changes.
  • Gated checks and gh-release jobs on the changes job output (with overrides for workflow_dispatch / merge_group where applicable).

Comment thread .github/workflows/deploy-website.yml
thinkall and others added 2 commits May 9, 2026 12:38
…ents:write to deploy

Address review: dorny/paths-filter@v3 calls the GitHub PR Files API on
pull_request events and needs `pull-requests: read`. Without it, the
`changes` job can fail with 403 on PRs and block downstream jobs via
`needs: changes`.

- Drop workflow-level `contents: write`; default to least-privilege
  `contents: read` and add `pull-requests: read` so the filter can read
  PR file lists.
- Move `contents: write` to the `gh-release` job only, where
  peaceiris/actions-gh-pages needs it to push to the gh-pages branch.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…read

Per review feedback, restore `contents: write` at the workflow level
(needed by gh-release for peaceiris/actions-gh-pages to push to
gh-pages) and just additively grant `pull-requests: read` so
dorny/paths-filter@v3 can read PR file lists via the GitHub API.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@thinkall thinkall merged commit 303d54c into main May 9, 2026
9 checks passed
@thinkall thinkall deleted the thinkall/docs-workflow-always-trigger-on-pr branch May 9, 2026 13:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants