feat: automate version and test count badges via GitHub Actions

[frankbria]

Problem

Version badges in README.md and CLAUDE.md require manual updates, leading to drift between actual state and documented state. This was caught during PR #137 review where badges showed v0.10.1 and 310 tests instead of v0.11.2 and 440 tests.

Proposed Solution

Implement a GitHub Actions workflow that automatically updates badges after:

1. Test suite runs (update test count)
2. Releases are published (update version)

Implementation Plan

Phase 1: Test Count Automation

Create .github/workflows/update-badges.yml:

name: Update Badges

on:
  push:
    branches: [main]
  workflow_run:
    workflows: ["CI"]
    types: [completed]
    branches: [main]

jobs:
  update-badges:
    runs-on: ubuntu-latest
    if: github.event.workflow_run.conclusion == 'success' || github.event_name == 'push'
    steps:
      - uses: actions/checkout@v4
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          
      - name: Install dependencies
        run: npm ci
      
      - name: Get test count
        run: |
          TEST_COUNT=$(npm test 2>&1 | grep -c "^ok " || echo "0")
          echo "TEST_COUNT=$TEST_COUNT" >> $GITHUB_ENV
          
      - name: Update badges if changed
        run: |
          # Update README.md test badge
          sed -i "s/tests-[0-9]*%20passing/tests-${TEST_COUNT}%20passing/" README.md
          
          # Update CLAUDE.md test count
          sed -i "s/Tests\*\*: [0-9]* passing/Tests**: ${TEST_COUNT} passing/" CLAUDE.md
          
      - name: Check for changes
        id: changes
        run: |
          if git diff --quiet; then
            echo "changed=false" >> $GITHUB_OUTPUT
          else
            echo "changed=true" >> $GITHUB_OUTPUT
          fi
          
      - name: Commit changes
        if: steps.changes.outputs.changed == 'true'
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add README.md CLAUDE.md
          git commit -m "chore: update test count badge to ${TEST_COUNT}"
          git push

Phase 2: Version Automation (Future)

When GitHub Releases are adopted:

• Trigger on release: [published]
• Extract version from release tag
• Update version badges in README.md, CLAUDE.md
• Consider using shields.io dynamic badges: ![Version](https://img.shields.io/github/v/release/frankbria/ralph-claude-code)

Files to Update

File	Badge Type	Current Format
README.md	Version	
README.md	Tests	
CLAUDE.md	Both	**Version**: vX.X.X | **Tests**: XXX passing

Acceptance Criteria

• Workflow runs after successful CI on main branch
• Test count badge updates automatically
• No workflow runs on badge-only commits (prevent infinite loop)
• Commit messages follow conventional commit format

Future Enhancements

• Integrate with GitHub Releases for version automation
• Consider switching to dynamic shields.io badges
• Add badge for code coverage percentage

Related

• PR fix(setup): create .ralphrc with consistent tool permissions #137 - Manual badge update that prompted this issue

[traycerai]

Plan

Observations

The repository currently has inconsistent badge values across documentation files. README.md shows v0.10.1 and 310 tests, while CLAUDE.md shows v0.11.1 and 424 tests. The existing CI workflow (file:.github/workflows/test.yml) runs tests on push to main/develop and PRs. Tests are written in BATS format with @test blocks across file:tests/unit/ and file:tests/integration/ directories. The test count can be determined by counting @test occurrences in .bats files. No centralized VERSION file exists, suggesting version is managed manually across multiple files.

Approach

Implement a two-phase automation strategy. Phase 1 focuses on test count automation using a GitHub Actions workflow triggered after successful CI runs on the main branch. The workflow will count tests by grepping @test in BATS files, then update badges in README.md and CLAUDE.md using sed replacements. To prevent infinite loops, the workflow will skip execution when the last commit is a badge update (detected via commit message pattern). Phase 2 (future enhancement) will handle version automation when GitHub Releases are adopted, using dynamic shields.io badges or release event triggers.

Implementation Steps

Phase 1: Test Count Badge Automation

1. Create Badge Update Workflow

Create file:.github/workflows/update-badges.yml with the following configuration:

Trigger Configuration:

• Trigger on workflow_run event when the "Test Suite" workflow completes successfully on the main branch
• Include a condition to skip if the triggering commit message starts with "chore: update test count badge" or "chore: update badges"

Workflow Jobs:

Job: update-test-count-badge

• Run on: ubuntu-latest
• Condition: github.event.workflow_run.conclusion == 'success'

Steps:

1. Checkout repository with write permissions

   • Use actions/checkout@v4
   • Set token: ${{ secrets.GITHUB_TOKEN }}
   • Set fetch-depth: 0 to access commit history

2. Check last commit message to prevent infinite loops

   • Extract last commit message using git log -1 --pretty=%B
   • If message matches pattern ^chore: update (test count )?badge, exit workflow with success
   • Store result in GITHUB_OUTPUT for conditional steps

3. Setup Node.js environment

   • Use actions/setup-node@v4
   • Set node-version to '20' (matching existing test.yml)

4. Install dependencies

   • Run npm ci to install BATS and test dependencies
   • Install jq for JSON processing: sudo apt-get update && sudo apt-get install -y jq

5. Count tests accurately

   • Use grep to count @test occurrences: grep -r "^@test" tests/ --include="*.bats" | wc -l
   • Store count in environment variable: TEST_COUNT
   • Add validation to ensure count is a positive integer
   • Echo the count for workflow logs: echo "Found $TEST_COUNT tests"

6. Update README.md badges

   • Update version badge pattern: s/version-[0-9.]*-blue/version-${VERSION}-blue/
   • Update test count badge pattern: s/tests-[0-9]*%20passing/tests-${TEST_COUNT}%20passing/
   • Use sed -i for in-place editing on Linux

7. Update CLAUDE.md metadata

   • Update the header line containing version and test count
   • Pattern: s/\*\*Version\*\*: v[0-9.]* | \*\*Tests\*\*: [0-9]* passing/\*\*Version\*\*: ${VERSION} | \*\*Tests\*\*: ${TEST_COUNT} passing/
   • Also update any other test count references in the file

8. Detect changes

   • Run git diff --quiet to check for modifications
   • Store result in GITHUB_OUTPUT as changed=true/false
   • List changed files for logging: git diff --name-only

9. Commit and push changes (conditional on changes detected)

   • Configure git user:
     • git config user.name "github-actions[bot]"
     • git config user.email "github-actions[bot]@users.noreply.github.com"
   • Stage files: git add README.md CLAUDE.md
   • Commit with conventional format: git commit -m "chore: update test count badge to ${TEST_COUNT}"
   • Push to main: git push

2. Handle Version Updates (Manual for Now)

Since there's no centralized VERSION file and GitHub Releases aren't being used:

Short-term approach:

• Version remains manually updated in README.md and CLAUDE.md
• Document the version update process in file:CONTRIBUTING.md
• Add a checklist for version bumps that includes updating both files

Preparation for Phase 2:

• Add a comment in the workflow file indicating where version automation will be added
• Document the planned approach using shields.io dynamic badges

3. Prevent Infinite Loop Scenarios

Multiple safeguards:

1. Commit message detection (primary safeguard)

   • Check if last commit message matches ^chore: update.*badge
   • Exit early if detected

2. Workflow trigger filtering

   • Only trigger on successful "Test Suite" workflow completion
   • Only run on main branch
   • Skip if workflow was triggered by github-actions[bot]

3. Change detection

   • Only commit if git diff shows actual changes
   • Prevents empty commits

4. Update Documentation

Update file:CONTRIBUTING.md:

• Add section "Badge Automation" explaining the automated test count updates
• Document that version badges are still manual (until Phase 2)
• Provide instructions for manual version updates

Update file:README.md:

• Add note in "Development Roadmap" section about automated badge updates
• Mention that test count badges are automatically updated after CI runs

Update file:CLAUDE.md:

• Add workflow documentation in the "CI/CD" section
• Explain the badge update automation for future contributors

Phase 2: Version Badge Automation (Future Enhancement)

When GitHub Releases are adopted:

1. Add release trigger to workflow

   • Trigger on: release: [published]
   • Extract version from github.event.release.tag_name
   • Remove 'v' prefix if present: ${tag_name#v}

2. Consider dynamic badges

   • Evaluate shields.io dynamic badges: https://img.shields.io/github/v/release/frankbria/ralph-claude-code
   • Benefits: No workflow needed, always up-to-date
   • Trade-off: Less control over badge format

3. Update both workflows

   • Modify test count workflow to also update version when available
   • Create separate release workflow if needed

Testing Strategy

Before merging:

1. Test workflow locally using act or similar tools
2. Test regex patterns with current badge formats
3. Verify commit message detection prevents loops
4. Test on a fork with actual GitHub Actions

After merging:

1. Monitor first automated run on main branch
2. Verify badges update correctly
3. Confirm no infinite loop occurs
4. Check commit message format

Acceptance Criteria Verification

• ✅ Workflow runs after successful CI on main branch
• ✅ Test count badge updates automatically
• ✅ No workflow runs on badge-only commits (infinite loop prevention)
• ✅ Commit messages follow conventional commit format (chore: update test count badge to N)
• ✅ Both README.md and CLAUDE.md are updated consistently

Workflow Diagram

sequenceDiagram
    participant Dev as Developer
    participant GH as GitHub (main branch)
    participant CI as Test Suite Workflow
    participant Badge as Update Badges Workflow
    
    Dev->>GH: Push code changes
    GH->>CI: Trigger test.yml
    CI->>CI: Run tests (npm test)
    
    alt Tests Pass
        CI->>Badge: Trigger update-badges.yml
        Badge->>Badge: Check last commit message
        
        alt Not a badge commit
            Badge->>Badge: Count tests (grep @test)
            Badge->>Badge: Update README.md badges
            Badge->>Badge: Update CLAUDE.md metadata
            Badge->>Badge: Detect changes
            
            alt Changes detected
                Badge->>GH: Commit "chore: update test count badge to N"
                Note over GH,Badge: Next CI run will skip badge update
            else No changes
                Badge->>Badge: Skip commit
            end
        else Is badge commit
            Badge->>Badge: Exit (prevent loop)
        end
    else Tests Fail
        CI->>CI: Workflow fails, no badge update
    end

Loading

File Changes Summary

File	Change Type	Description
file:.github/workflows/update-badges.yml	Create	New workflow for badge automation
file:CONTRIBUTING.md	Update	Document badge automation process
file:README.md	Update	Add note about automated badges
file:CLAUDE.md	Update	Document workflow in CI/CD section

Import In IDE

🤖 Prompt for AI Agents

## Observations

The repository currently has inconsistent badge values across documentation files. README.md shows v0.10.1 and 310 tests, while CLAUDE.md shows v0.11.1 and 424 tests. The existing CI workflow (`file:.github/workflows/test.yml`) runs tests on push to main/develop and PRs. Tests are written in BATS format with `@test` blocks across `file:tests/unit/` and `file:tests/integration/` directories. The test count can be determined by counting `@test` occurrences in `.bats` files. No centralized VERSION file exists, suggesting version is managed manually across multiple files.

## Approach

Implement a two-phase automation strategy. **Phase 1** focuses on test count automation using a GitHub Actions workflow triggered after successful CI runs on the main branch. The workflow will count tests by grepping `@test` in BATS files, then update badges in README.md and CLAUDE.md using sed replacements. To prevent infinite loops, the workflow will skip execution when the last commit is a badge update (detected via commit message pattern). **Phase 2** (future enhancement) will handle version automation when GitHub Releases are adopted, using dynamic shields.io badges or release event triggers.

## Implementation Steps

### Phase 1: Test Count Badge Automation

#### 1. Create Badge Update Workflow

Create `file:.github/workflows/update-badges.yml` with the following configuration:

**Trigger Configuration:**
- Trigger on `workflow_run` event when the "Test Suite" workflow completes successfully on the main branch
- Include a condition to skip if the triggering commit message starts with "chore: update test count badge" or "chore: update badges"

**Workflow Jobs:**

**Job: update-test-count-badge**
- Run on: `ubuntu-latest`
- Condition: `github.event.workflow_run.conclusion == 'success'`

**Steps:**

1. **Checkout repository** with write permissions
   - Use `actions/checkout@v4`
   - Set `token: ${{ secrets.GITHUB_TOKEN }}`
   - Set `fetch-depth: 0` to access commit history

2. **Check last commit message** to prevent infinite loops
   - Extract last commit message using `git log -1 --pretty=%B`
   - If message matches pattern `^chore: update (test count )?badge`, exit workflow with success
   - Store result in `GITHUB_OUTPUT` for conditional steps

3. **Setup Node.js environment**
   - Use `actions/setup-node@v4`
   - Set node-version to '20' (matching existing test.yml)

4. **Install dependencies**
   - Run `npm ci` to install BATS and test dependencies
   - Install `jq` for JSON processing: `sudo apt-get update && sudo apt-get install -y jq`

5. **Count tests accurately**
   - Use grep to count `@test` occurrences: `grep -r "^@test" tests/ --include="*.bats" | wc -l`
   - Store count in environment variable: `TEST_COUNT`
   - Add validation to ensure count is a positive integer
   - Echo the count for workflow logs: `echo "Found $TEST_COUNT tests"`

6. **Update README.md badges**
   - Update version badge pattern: `s/version-[0-9.]*-blue/version-${VERSION}-blue/`
   - Update test count badge pattern: `s/tests-[0-9]*%20passing/tests-${TEST_COUNT}%20passing/`
   - Use `sed -i` for in-place editing on Linux

7. **Update CLAUDE.md metadata**
   - Update the header line containing version and test count
   - Pattern: `s/\*\*Version\*\*: v[0-9.]* | \*\*Tests\*\*: [0-9]* passing/\*\*Version\*\*: ${VERSION} | \*\*Tests\*\*: ${TEST_COUNT} passing/`
   - Also update any other test count references in the file

8. **Detect changes**
   - Run `git diff --quiet` to check for modifications
   - Store result in `GITHUB_OUTPUT` as `changed=true/false`
   - List changed files for logging: `git diff --name-only`

9. **Commit and push changes** (conditional on changes detected)
   - Configure git user:
     - `git config user.name "github-actions[bot]"`
     - `git config user.email "github-actions[bot]@users.noreply.github.com"`
   - Stage files: `git add README.md CLAUDE.md`
   - Commit with conventional format: `git commit -m "chore: update test count badge to ${TEST_COUNT}"`
   - Push to main: `git push`

#### 2. Handle Version Updates (Manual for Now)

Since there's no centralized VERSION file and GitHub Releases aren't being used:

**Short-term approach:**
- Version remains manually updated in README.md and CLAUDE.md
- Document the version update process in `file:CONTRIBUTING.md`
- Add a checklist for version bumps that includes updating both files

**Preparation for Phase 2:**
- Add a comment in the workflow file indicating where version automation will be added
- Document the planned approach using shields.io dynamic badges

#### 3. Prevent Infinite Loop Scenarios

**Multiple safeguards:**

1. **Commit message detection** (primary safeguard)
   - Check if last commit message matches `^chore: update.*badge`
   - Exit early if detected

2. **Workflow trigger filtering**
   - Only trigger on successful "Test Suite" workflow completion
   - Only run on main branch
   - Skip if workflow was triggered by github-actions[bot]

3. **Change detection**
   - Only commit if `git diff` shows actual changes
   - Prevents empty commits

#### 4. Update Documentation

**Update `file:CONTRIBUTING.md`:**
- Add section "Badge Automation" explaining the automated test count updates
- Document that version badges are still manual (until Phase 2)
- Provide instructions for manual version updates

**Update `file:README.md`:**
- Add note in "Development Roadmap" section about automated badge updates
- Mention that test count badges are automatically updated after CI runs

**Update `file:CLAUDE.md`:**
- Add workflow documentation in the "CI/CD" section
- Explain the badge update automation for future contributors

### Phase 2: Version Badge Automation (Future Enhancement)

**When GitHub Releases are adopted:**

1. **Add release trigger to workflow**
   - Trigger on: `release: [published]`
   - Extract version from `github.event.release.tag_name`
   - Remove 'v' prefix if present: `${tag_name#v}`

2. **Consider dynamic badges**
   - Evaluate shields.io dynamic badges: `https://img.shields.io/github/v/release/frankbria/ralph-claude-code`
   - Benefits: No workflow needed, always up-to-date
   - Trade-off: Less control over badge format

3. **Update both workflows**
   - Modify test count workflow to also update version when available
   - Create separate release workflow if needed

### Testing Strategy

**Before merging:**

1. **Test workflow locally** using `act` or similar tools
2. **Test regex patterns** with current badge formats
3. **Verify commit message detection** prevents loops
4. **Test on a fork** with actual GitHub Actions

**After merging:**

1. Monitor first automated run on main branch
2. Verify badges update correctly
3. Confirm no infinite loop occurs
4. Check commit message format

### Acceptance Criteria Verification

- ✅ Workflow runs after successful CI on main branch
- ✅ Test count badge updates automatically  
- ✅ No workflow runs on badge-only commits (infinite loop prevention)
- ✅ Commit messages follow conventional commit format (`chore: update test count badge to N`)
- ✅ Both README.md and CLAUDE.md are updated consistently

### Workflow Diagram

```mermaid
sequenceDiagram
    participant Dev as Developer
    participant GH as GitHub (main branch)
    participant CI as Test Suite Workflow
    participant Badge as Update Badges Workflow
    
    Dev->>GH: Push code changes
    GH->>CI: Trigger test.yml
    CI->>CI: Run tests (npm test)
    
    alt Tests Pass
        CI->>Badge: Trigger update-badges.yml
        Badge->>Badge: Check last commit message
        
        alt Not a badge commit
            Badge->>Badge: Count tests (grep @test)
            Badge->>Badge: Update README.md badges
            Badge->>Badge: Update CLAUDE.md metadata
            Badge->>Badge: Detect changes
            
            alt Changes detected
                Badge->>GH: Commit "chore: update test count badge to N"
                Note over GH,Badge: Next CI run will skip badge update
            else No changes
                Badge->>Badge: Skip commit
            end
        else Is badge commit
            Badge->>Badge: Exit (prevent loop)
        end
    else Tests Fail
        CI->>CI: Workflow fails, no badge update
    end
```

### File Changes Summary

| File | Change Type | Description |
|------|-------------|-------------|
| `file:.github/workflows/update-badges.yml` | Create | New workflow for badge automation |
| `file:CONTRIBUTING.md` | Update | Document badge automation process |
| `file:README.md` | Update | Add note about automated badges |
| `file:CLAUDE.md` | Update | Document workflow in CI/CD section |

---

Execution Information

Branch: main
Commit: 33739e0

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

---

🔗 Related PRs

#8 - docs: update CLAUDE.md and README.md with recent improvements [merged]
#52 - test(cli): add comprehensive CLI argument parsing tests [merged]
#59 - test(install): add comprehensive installation tests [merged]
#67 - feat(import): modernize ralph_import.sh with JSON output parsing [merged]
#135 - ci(workflow): add concurrency blocks to prevent duplicate runs [merged]

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[github-actions]

✨ Triage: Enhancement

This issue has been labeled as an enhancement. Automating version and test-count badge updates via GitHub Actions is a great quality-of-life improvement that reduces manual drift.

The proposed approach is well-scoped. A few notes for implementation:

• Make sure the workflow skips triggering itself on badge-only commits (add [skip ci] or check commit author)
• Consider using shields.io dynamic badges tied to GitHub Releases for the version badge to avoid write-back commits entirely
• The test count extraction (grep -c "^ok ") works for TAP-style bats output — confirm this still works with npm test's output format

This is a good candidate for a first-time contributor given the clear acceptance criteria.

Generated by Issue Triage Assistant