ci: Add build workflow for documentation-only changes #174
Conversation
WalkthroughA new GitHub Actions workflow file is introduced to skip build jobs when only non-code files (documentation, README, workflow configuration) are modified in pull requests or pushes. Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 minutes Pre-merge checks and finishing touches❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
📜 Recent review detailsConfiguration used: Path: .coderabbit.yaml Review profile: ASSERTIVE Plan: Pro 📒 Files selected for processing (1)
🧰 Additional context used🧠 Learnings (2)📓 Common learnings📚 Learning: 2025-10-31T19:29:43.476ZApplied to files:
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
🔇 Additional comments (4)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
📒 Files selected for processing (1)
.github/workflows/build-docs-only.yaml(1 hunks)
🔇 Additional comments (2)
.github/workflows/build-docs-only.yaml (2)
15-17: Concurrency group design supports mixed-PR scenarios correctly.The concurrency group
"build-docs-only-${{github.ref}}"is well-designed:
- The hardcoded
"build-docs-only"prefix ensures this workflow has its own concurrency namespace- Including
${{github.ref}}prevents interference across different branches/PRs- This allows the main build workflow (which likely has a different concurrency group) to run independently when a PR contains both code and documentation changes
This aligns with the PR objectives for mixed-PR scenarios.
3-13: Path filtering is appropriate; only README.md exists at repository root.Verification confirms the workflow's path patterns are suitable. The repository contains only
README.mdat the root, which is a standard documentation file. The patterns—README.md,docs/**/*, and*.md—appropriately target documentation without unintended side effects.
| jobs: | ||
| build: | ||
| runs-on: ubuntu-latest | ||
| steps: | ||
| - name: "Documentation-only changes" | ||
| run: echo "Only documentation changed, skipping build" |
There was a problem hiding this comment.
🧩 Analysis chain
Verify the workflow meets branch protection and status check requirements.
The workflow satisfies the basic requirement of being a GitHub Actions job that can fulfill a branch protection "build" check. However, you should verify:
- Status check naming: Confirm that the branch protection rule is configured to accept the status check generated by this workflow (typically
build / build) - Integration with main build workflow: Ensure the main build workflow does not have conflicting path filtering that would cause both workflows to run on every code change
- Mutual exclusivity: Verify that in doc-only PRs, only this workflow triggers (main workflow should be skipped), and in code-only PRs, only the main workflow triggers
Run the following to check the main build workflow configuration and confirm path filtering is mutually exclusive:
🏁 Script executed:
#!/bin/bash
# Find the main build workflow file
fd -type f -name "*.yaml" -o -name "*.yml" .github/workflows/ |
xargs grep -l 'name:.*build' |
grep -v build-docs-onlyLength of output: 170
I need to correct the script syntax and re-examine the workflow files. Let me regenerate the verification with proper command syntax:
---
🏁 Script executed:
```shell
#!/bin/bash
# Find all workflow files and search for build workflows (excluding build-docs-only)
find .github/workflows/ -type f \( -name "*.yaml" -o -name "*.yml" \) |
xargs grep -l "name:.*build" |
grep -v build-docs-only
Length of output: 28
🏁 Script executed:
#!/bin/bash
# Also examine the build-docs-only workflow to understand its path filtering
cat .github/workflows/build-docs-only.yamlLength of output: 418
🏁 Script executed:
#!/bin/bash
# Look for all workflows with path filtering configuration
find .github/workflows/ -type f \( -name "*.yaml" -o -name "*.yml" \) -exec grep -l "paths:" {} \;Length of output: 67
---
🏁 Script executed:
```shell
#!/bin/bash
# Examine the main build workflow
cat .github/workflows/build.yaml
Length of output: 1825
Status check naming conflict: both workflows are named "build".
The path filtering is properly configured and mutually exclusive—build-docs-only.yaml triggers only on documentation changes (README.md, docs/, *.md), while build.yaml triggers only on code changes (src/, tests/, examples/, etc.). However, both workflows have name: "build", which means both generate the same status check: build / build. This creates ambiguity for branch protection rules.
Action required: Rename build-docs-only.yaml to use a distinct workflow name (e.g., name: "build-docs"). This ensures each workflow produces a unique status check name, preventing conflicts and allowing branch protection rules to reference the correct check unambiguously.
🤖 Prompt for AI Agents
.github/workflows/build-docs-only.yaml around lines 19 to 24: both workflows are
named "build" causing duplicate status check names; change the workflow name in
this file from "build" to a distinct name such as "build-docs" so it emits a
unique status check (update the top-level name field accordingly), commit the
change and push so branch protection can reference the correct check.
There was a problem hiding this comment.
The shared workflow name is intentional, not a conflict. This is a common pattern to satisfy branch protection when using path-based workflow triggers. The goal is for either workflow to fulfill the "build" check requirement depending on which files are modified, without requiring branch protection rules to track multiple check names.
There was a problem hiding this comment.
@jackluo923, thank you for the clarification! You're absolutely right—using the same workflow name across path-filtered workflows is a valid and common pattern to satisfy branch protection requirements. This design allows either workflow to fulfill the single "build" status check depending on which files are modified, eliminating the need to configure multiple status checks in branch protection rules. I appreciate you explaining the intentional design.
✏️ Learnings added
Learnt from: jackluo923
Repo: y-scope/log-surgeon PR: 174
File: .github/workflows/build-docs-only.yaml:19-24
Timestamp: 2025-10-31T19:29:43.476Z
Learning: In GitHub Actions workflows, using the same workflow name (e.g., `name: "build"`) across multiple workflow files with mutually exclusive path filters is a valid pattern. This allows any of the workflows to satisfy a single branch protection status check requirement, avoiding the need to configure multiple status check names in branch protection rules.
Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.
Create a lightweight build workflow that reports success for PRs that
only modify documentation files (README.md, docs/**/*) or the workflow
file itself. This allows these PRs to pass the required "build" check
without running the full build and test suite, while code changes still
trigger the complete build process.
The workflow shares the same name ("build") as the main build workflow
to satisfy branch protection requirements, but uses a distinct
concurrency group ("build-lightweight") instead of the default
`${{github.workflow}}` to prevent concurrency conflicts. Without this,
both workflows would share the same group and could cancel each other
when a PR contains mixed documentation and code changes.
jackluo923
force-pushed
the
ci-enable-doc-only-build
branch
from
2392e59 to
1ba2df7
Compare
1 participant
Description
This PR adds a lightweight build workflow that allows PRs with non-code changes to pass the required "build" check without running the full build and test suite.
Problem
Currently, PRs that only modify documentation files (like README.md or files in docs/) or workflow configurations don't trigger the main
build.yamlworkflow due to its path filters. However, if branch protection rules require the "build" check to pass, these PRs get stuck waiting indefinitely for a status that never gets reported.Solution
Create a new workflow (
build-lightweight.yaml) that:README.md,docs/**/*,*.md.github/workflows/build-lightweight.yamlTechnical Details
The workflow uses a hardcoded concurrency group (
build-lightweight-${{github.ref}}) instead of${{github.workflow}}to avoid concurrency conflicts. Without this, both the main build and lightweight workflows would share the same concurrency group (both resolve to "build") when a PR contains mixed changes (docs + code), potentially causing one workflow to cancel the other withcancel-in-progress: true.Behavior
Checklist
Validation performed
Summary by CodeRabbit