feat: add OpenSpec metric badges to README#767
feat: add OpenSpec metric badges to README#767mipmip wants to merge 2 commits intoFission-AI:mainfrom
Conversation
Add a new row of OpenSpec badges displaying project health metrics: - number_of_specs: specification count - open_changes: active change count - tasks_status: task completion ratio Includes GitHub Actions workflow using weAretechnative/openspec-badge-action to generate badges on push to main. Note: Project owner must enable GitHub Pages (gh-pages branch) after merge for badges to display correctly. Or a shorter version if you prefer: feat: add OpenSpec metric badges to README Add badges for specs count, open changes, and tasks status using openspec-badge-action. Requires GitHub Pages setup post-merge.
|
Task completed. Here is my review of PR #767: PR Review: feat: add OpenSpec metric badges to README (#767)SummaryThis PR adds OpenSpec-specific metric badges to the README and introduces a GitHub Actions workflow to generate them. It also includes a full set of OpenSpec change documentation (proposal, design, spec, tasks). The actual code changes are small — a new workflow file and 6 lines added to the README — while the bulk of the diff is documentation. Issues1. Badge URLs point to this repository, not a fork — but will be broken until post-merge setupREADME.md lines 17-19 — The badge These will render as broken images immediately after merge because:
The PR description mentions this, but it's worth considering whether broken badges in the README (even temporarily) are acceptable on 2. GitHub Action pinned to
|
📝 WalkthroughWalkthroughThis pull request introduces OpenSpec badge integration by adding a GitHub Actions workflow that generates metrics-based badges on main branch pushes, integrating three badges (specs count, open changes, task status) into the README, and documenting the implementation approach through design, proposal, and specification files. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~15 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Tip Try Coding Plans. Let us write the prompt for your AI agent so you can ship faster (with fewer bugs). 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 |
Greptile SummaryAdds OpenSpec metric badges to README header, displaying project health metrics (specs count, open changes, and task completion ratio). Includes a GitHub Actions workflow that generates SVG badges on push to main and publishes them to the gh-pages branch. Key changes:
The implementation is clean and follows existing conventions. Documentation is thorough with clear post-merge prerequisites for the project owner. Confidence Score: 4.5/5
Important Files Changed
Last reviewed commit: 785db8a |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| contents: write | ||
| steps: | ||
| - uses: actions/checkout@v4 | ||
| - uses: weAretechnative/openspec-badge-action@main |
There was a problem hiding this comment.
using @main reference could introduce breaking changes if the action is updated
| - uses: weAretechnative/openspec-badge-action@main | |
| - uses: weAretechnative/openspec-badge-action@v1 |
consider pinning to a specific version tag or commit SHA for stability
Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.github/workflows/openspec-badge.yml:
- Around line 3-6: The workflow currently only triggers on push to main; add a
manual trigger by updating the "on" triggers in the openspec-badge.yml to
include workflow_dispatch alongside push so the badge workflow can be invoked
from the Actions UI (modify the top-level "on" block in the existing file to
include workflow_dispatch).
- Around line 13-14: Replace mutable action references with immutable commit
SHAs: change uses: actions/checkout@v4 to uses: actions/checkout@<commit-sha>
and uses: weAretechnative/openspec-badge-action@main to uses:
weAretechnative/openspec-badge-action@<commit-sha>; locate the two lines
containing actions/checkout and weAretechnative/openspec-badge-action in the
workflow file and update them to the exact commit SHAs (not tags or branches),
ensuring you pick the intended release commit for each action and verify the SHA
on the action repository before committing.
In `@openspec/changes/add-openspec-badges/design.md`:
- Around line 10-17: Update the Goals and Non-Goals sections so metric names are
consistent with the decision and workflow; replace ambiguous or conflicting
names—ensure Goals list uses the exact metric identifiers used elsewhere
(number_of_specs, number_of_open_changes, number_of_open_tasks) and remove or
rename Non-Goals entries that reference different identifiers
(number_of_requirements, tasks_status) to match the chosen metrics (e.g., change
tasks_status → number_of_open_tasks or list it explicitly as out-of-scope), and
reflect the workflow names (open_changes) exactly where referenced to eliminate
contradictions between Goals/Non-Goals and the workflow/decision text.
In `@openspec/changes/add-openspec-badges/proposal.md`:
- Around line 9-10: Change the wording "open tasks" to match the implemented
metric name `tasks_status` (or "tasks_status (ratio)" for clarity) so the
proposal and implementation use the same term; update the list line that
currently reads “open tasks” to instead read `tasks_status` (or `tasks_status
(ratio)`) to avoid ambiguity and ensure consistency with the implemented metric.
ℹ️ Review info
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (7)
.github/workflows/openspec-badge.ymlREADME.mdopenspec/changes/add-openspec-badges/.openspec.yamlopenspec/changes/add-openspec-badges/design.mdopenspec/changes/add-openspec-badges/proposal.mdopenspec/changes/add-openspec-badges/specs/readme-badges/spec.mdopenspec/changes/add-openspec-badges/tasks.md
| on: | ||
| push: | ||
| branches: [main] | ||
|
|
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Verify workflow file current state and check for manual trigger documentation
echo "=== Current workflow trigger configuration ==="
cat -n .github/workflows/openspec-badge.yml | head -20
echo -e "\n=== Searching for manual trigger mentions in documentation ==="
# Search broadly in the repository for manual trigger references
rg -i 'manually trigger|manual trigger|run the workflow' --type md || echo "No matches found in markdown files"
echo -e "\n=== Searching for workflow_dispatch in workflow files ==="
rg 'workflow_dispatch' .github/workflows/ || echo "No workflow_dispatch found in any workflows"
echo -e "\n=== Checking if openspec-badge.yml exists and is as described ==="
ls -la .github/workflows/openspec-badge.yml
wc -l .github/workflows/openspec-badge.ymlRepository: Fission-AI/OpenSpec
Length of output: 1826
Add workflow_dispatch trigger for manual runs from Actions UI.
The task explicitly requires "Manually trigger or wait for the badge workflow to run on main branch" (task 4.2), but the workflow currently only supports automatic runs on push. Add workflow_dispatch to enable manual triggering from the GitHub Actions UI.
Suggested change
on:
push:
branches: [main]
+ workflow_dispatch:📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| on: | |
| push: | |
| branches: [main] | |
| on: | |
| push: | |
| branches: [main] | |
| workflow_dispatch: |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.github/workflows/openspec-badge.yml around lines 3 - 6, The workflow
currently only triggers on push to main; add a manual trigger by updating the
"on" triggers in the openspec-badge.yml to include workflow_dispatch alongside
push so the badge workflow can be invoked from the Actions UI (modify the
top-level "on" block in the existing file to include workflow_dispatch).
| - uses: actions/checkout@v4 | ||
| - uses: weAretechnative/openspec-badge-action@main |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# First, check if the file exists and read the relevant lines
if [ -f ".github/workflows/openspec-badge.yml" ]; then
echo "=== File exists, showing full content ==="
cat -n ".github/workflows/openspec-badge.yml"
else
echo "File not found, searching for similar files:"
find . -name "*openspec*" -o -name "*badge*" | head -20
fiRepository: Fission-AI/OpenSpec
Length of output: 607
🏁 Script executed:
# Also run the provided verification script
rg -nP '^\s*-\s*uses:\s*[^@]+@(main|master|v\d+)$' .github/workflowsRepository: Fission-AI/OpenSpec
Length of output: 461
🌐 Web query:
GitHub Actions best practices action pinning security v4 major version tag
💡 Result:
Best practice: don’t rely on @v4 for security—pin to a commit SHA
Why actions/checkout@v4 (major tag) is risky
- A major tag like
@v4is a floating reference that can be moved to a newer commit, so your workflow can start running new code without review. [1] - Even “more specific” tags (like
v4.1.1) can be force-moved if the publisher retags them, unless you’re using a truly immutable mechanism; SHA pinning avoids tag-move attacks. [2] - GitHub’s own guidance: the most reliable immutable reference is a full-length commit SHA (and immutable tags can be disabled by repo owners). [1]
Recommended pattern (secure + maintainable)
Pin to the full commit SHA, and keep the human-readable version as a comment:
- uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7This is explicitly recommended by GitHub’s security guidance (and helps tooling like Dependabot track upgrades when you pin a SHA that corresponds to a tagged release). [1]
If you run GitHub at org/enterprise scale
- GitHub policies can require actions to be pinned to a full-length commit SHA (so unpinned workflows fail). [3]
- GitHub also added explicit “enforce SHA pinning” support in the allowed-actions policy controls. [4]
Note on “immutable releases/tags”
GitHub supports “immutable releases,” but Git tags in general can be force-moved (GitHub even documents force-updating tags), which is exactly why SHA pinning is the safest default for consumers. [5]
Bottom line: treat @v4 as convenience, not a security control—use @<full sha> for third-party actions, and automate updates/reviews. [1][2]
Sources: [1] GitHub Well-Architected Actions security guidance, [2] OpenSSF workflow attack vectors, [3] GitHub Docs (enterprise policy requiring SHA pinning), [4] GitHub Changelog (SHA pinning enforcement), [5] GitHub Docs on managing releases/tags (force-updating tags).
🌐 Web query:
actions/checkout@v4 pinning commit SHA security recommendation GitHub
💡 Result:
GitHub’s security guidance is to pin GitHub Actions (including actions/checkout@v4) to an immutable, full-length commit SHA instead of a mutable tag like v4, to reduce supply-chain risk (e.g., a tag being moved to different code). (wellarchitected.github.com)
Example:
- uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7This keeps builds reproducible and avoids silently picking up changes if the v4 tag moves. GitHub also supports enforcing SHA pinning via Actions policy so workflows fail if actions aren’t pinned. (github.blog)
Citations:
- 1: https://wellarchitected.github.com/library/application-security/recommendations/actions-security/?utm_source=openai
- 2: https://github.blog/changelog/2025-08-15-github-actions-policy-now-supports-blocking-and-sha-pinning-actions/?utm_source=openai
🌐 Web query:
GitHub Actions reproducibility mutable action references major version tags 2024 2025
💡 Result:
- Major version tags (e.g.,
owner/action@v4) are intentionally “moving” references: action authors are expected to update thevNtag to point at the latest compatible minor/patch release, so your workflow is not reproducible over time if you rely on@vN. GitHub’s own guidance for action authors explicitly describes moving major (and minor) tags by force-updating tags. [1] - Any Git tag (even
@v4.1.1) can be mutable unless the repo uses GitHub “immutable releases.” Without immutability, an attacker (or maintainer) can retarget an existing tag to a different commit, breaking both security and reproducibility; the OpenSSF notes this explicitly and recommends SHA pinning as the robust mitigation. [2] - Best practice for reproducibility + supply-chain safety (2024–2025 guidance): pin to a full commit SHA (optionally with a comment noting the human version), e.g.
uses: actions/checkout@<full_sha> # v4.1.7. GitHub’s Well-Architected guidance calls full-SHA pinning the most reliable immutable reference. [3] - If you want “version semantics” without SHAs, use tags from an immutable release (where the release’s tag can’t be moved). GitHub Docs: immutable releases lock the tag to a commit and generate release attestations. [4]
- Org/enterprise enforcement (added in 2025): GitHub Actions policy can now require SHA pinning (and also block specific actions/versions), causing workflows that use non-SHA action refs to fail. [5]
- Why this mattered in 2025: real incidents showed attackers repointing many existing tags to malicious commits (e.g.,
tj-actions/changed-files), which immediately impacted users who referenced tags. [6]
Rule of thumb:
- For maximum reproducibility: pin every third-party action to a full commit SHA. [3]
- For easier updates with guardrails: use SHA pinning + Dependabot/Renovate to propose upgrades (so updates are reviewed), or only trust immutable releases where available. [3][4]
Sources
[1] GitHub Docs — “Using immutable releases and tags to manage your action’s releases” (docs.github.com)
[2] OpenSSF — “Mitigating Attack Vectors in GitHub Workflows” (openssf.org)
[3] GitHub Well-Architected — “Securing GitHub Actions Workflows” (wellarchitected.github.com)
[4] GitHub Docs — “Immutable releases” (docs.github.com)
[5] GitHub Changelog (2025-08-15) — Actions policy supports blocking + SHA pinning (github.blog)
[6] StepSecurity — incident writeup referencing tag repointing compromises (Mar 2025) (stepsecurity.io)
Citations:
- 1: https://docs.github.com/en/actions/how-tos/create-and-publish-actions/using-immutable-releases-and-tags-to-manage-your-actions-releases?utm_source=openai
- 2: https://openssf.org/blog/2024/08/12/mitigating-attack-vectors-in-github-workflows/?utm_source=openai
- 3: https://wellarchitected.github.com/library/application-security/recommendations/actions-security/?utm_source=openai
- 4: https://docs.github.com/en/code-security/concepts/supply-chain-security/immutable-releases?utm_source=openai
- 5: https://github.blog/changelog/2025-08-15-github-actions-policy-now-supports-blocking-and-sha-pinning-actions/?utm_source=openai
- 6: https://www.stepsecurity.io/blog/suspicious-tag-movement-in-aws-github-action?utm_source=openai
Pin actions to immutable commit SHAs.
Line 13 uses @v4 (a mutable major tag that moves with releases), and Line 14 uses @main (explicitly mutable). GitHub's security guidance recommends pinning both actions to full commit SHAs to improve reproducibility and reduce supply-chain risk.
Suggested change
- - uses: actions/checkout@v4
- - uses: weAretechnative/openspec-badge-action@main
+ - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
+ - uses: weAretechnative/openspec-badge-action@<full_commit_sha>🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.github/workflows/openspec-badge.yml around lines 13 - 14, Replace mutable
action references with immutable commit SHAs: change uses: actions/checkout@v4
to uses: actions/checkout@<commit-sha> and uses:
weAretechnative/openspec-badge-action@main to uses:
weAretechnative/openspec-badge-action@<commit-sha>; locate the two lines
containing actions/checkout and weAretechnative/openspec-badge-action in the
workflow file and update them to the exact commit SHAs (not tags or branches),
ensuring you pick the intended release commit for each action and verify the SHA
on the action repository before committing.
| - Add three OpenSpec metric badges to README: number_of_specs, number_of_open_changes, number_of_open_tasks | ||
| - Configure GitHub Action workflow to generate badges on push to main | ||
| - Use classic style with labels enabled for visual consistency | ||
|
|
||
| **Non-Goals:** | ||
| - Modifying existing badge styling or arrangement | ||
| - Adding all available badge types (number_of_requirements, tasks_status) | ||
| - Custom badge colors or branding |
There was a problem hiding this comment.
Resolve metric-name contradictions in Goals/Non-Goals.
Goals/Non-Goals conflict with the actual decision and workflow (open_changes, tasks_status).
Suggested consistency fix
- - Add three OpenSpec metric badges to README: number_of_specs, number_of_open_changes, number_of_open_tasks
+ - Add three OpenSpec metric badges to README: number_of_specs, open_changes, tasks_status
...
- - Adding all available badge types (number_of_requirements, tasks_status)
+ - Adding additional badge types beyond the selected three (e.g., number_of_requirements)Also applies to: 23-23
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@openspec/changes/add-openspec-badges/design.md` around lines 10 - 17, Update
the Goals and Non-Goals sections so metric names are consistent with the
decision and workflow; replace ambiguous or conflicting names—ensure Goals list
uses the exact metric identifiers used elsewhere (number_of_specs,
number_of_open_changes, number_of_open_tasks) and remove or rename Non-Goals
entries that reference different identifiers (number_of_requirements,
tasks_status) to match the chosen metrics (e.g., change tasks_status →
number_of_open_tasks or list it explicitly as out-of-scope), and reflect the
workflow names (open_changes) exactly where referenced to eliminate
contradictions between Goals/Non-Goals and the workflow/decision text.
| - Display three metrics: number of specs, open changes, and open tasks | ||
| - Use classic style with labels for consistency and clarity |
There was a problem hiding this comment.
Align metric wording with implementation (tasks_status).
Line 9 says “open tasks”, but the implemented metric is tasks_status (ratio). Please use the same term here to avoid ambiguity.
Suggested doc fix
-- Display three metrics: number of specs, open changes, and open tasks
+- Display three metrics: number_of_specs, open_changes, and tasks_status📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - Display three metrics: number of specs, open changes, and open tasks | |
| - Use classic style with labels for consistency and clarity | |
| - Display three metrics: number_of_specs, open_changes, and tasks_status | |
| - Use classic style with labels for consistency and clarity |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@openspec/changes/add-openspec-badges/proposal.md` around lines 9 - 10, Change
the wording "open tasks" to match the implemented metric name `tasks_status` (or
"tasks_status (ratio)" for clarity) so the proposal and implementation use the
same term; update the list line that currently reads “open tasks” to instead
read `tasks_status` (or `tasks_status (ratio)`) to avoid ambiguity and ensure
consistency with the implemented metric.
2 participants
Add a new row of OpenSpec badges displaying project health metrics:
Includes GitHub Actions workflow using weAretechnative/openspec-badge-action to generate badges on push to main.
Note: Project owner must enable GitHub Pages (gh-pages branch) after merge for badges to display correctly. Check tasks.md in change.
Summary by CodeRabbit