Skip to content

github-action.md

Latest commit

 

History

History
275 lines (213 loc) · 5.84 KB

github-action.md

File metadata and controls

275 lines (213 loc) · 5.84 KB
Raw

GitHub Action

cclint provides a GitHub Action for easy integration into your CI/CD pipelines. This allows you to automatically lint CLAUDE.md files on every push and pull request.

Quick Start

Add this workflow to .github/workflows/lint-claude.yml:

name: Lint CLAUDE.md

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main, develop ]

jobs:
  lint-claude:
    runs-on: ubuntu-latest
    name: Lint CLAUDE.md files
    
    steps:
    - name: Checkout code
      uses: actions/checkout@v4
      
    - name: Lint CLAUDE.md files
      uses: felixgeelhaar/cclint@v0.1.2
      with:
        files: 'CLAUDE.md'
        format: 'text'
        fail-on-error: 'true'

Inputs

Input Description Required Default
files Files to lint (glob pattern or space-separated list) No CLAUDE.md
format Output format (text or json) No text
max-size Maximum file size in characters No 10000
fail-on-error Fail the action if errors are found No true
config-file Path to configuration file No Auto-detected

Outputs

Output Description
results Linting results in JSON format
error-count Number of errors found
warning-count Number of warnings found

Examples

Basic Usage

- name: Lint CLAUDE.md
  uses: felixgeelhaar/cclint@v0.1.2
  with:
    files: 'CLAUDE.md'

Multiple Files

- name: Lint multiple CLAUDE.md files
  uses: felixgeelhaar/cclint@v0.1.2
  with:
    files: 'CLAUDE.md docs/CLAUDE.md src/CLAUDE.md'
    format: 'json'

Glob Patterns

- name: Lint all CLAUDE.md files
  uses: felixgeelhaar/cclint@v0.1.2
  with:
    files: '**/CLAUDE.md'
    max-size: '15000'

Custom Configuration

- name: Lint with custom config
  uses: felixgeelhaar/cclint@v0.1.2
  with:
    files: 'CLAUDE.md'
    config-file: '.github/cclint-config.json'

Don't Fail on Errors

- name: Lint but continue on errors
  uses: felixgeelhaar/cclint@v0.1.2
  with:
    files: 'CLAUDE.md'
    fail-on-error: 'false'
  continue-on-error: true

Using Outputs

- name: Lint CLAUDE.md
  id: lint
  uses: felixgeelhaar/cclint@v0.1.2
  with:
    files: 'CLAUDE.md'
    format: 'json'
    
- name: Comment PR with results
  if: github.event_name == 'pull_request'
  uses: actions/github-script@v7
  with:
    script: |
      const results = JSON.parse('${{ steps.lint.outputs.results }}');
      const errorCount = '${{ steps.lint.outputs.error-count }}';
      const warningCount = '${{ steps.lint.outputs.warning-count }}';
      
      let comment = `## 📝 CLAUDE.md Lint Results\n\n`;
      comment += `- **Errors:** ${errorCount}\n`;
      comment += `- **Warnings:** ${warningCount}\n\n`;
      
      if (results.length > 0) {
        comment += `<details>\n<summary>Detailed Results</summary>\n\n`;
        comment += '```json\n' + JSON.stringify(results, null, 2) + '\n```\n';
        comment += `</details>`;
      }
      
      github.rest.issues.createComment({
        issue_number: context.issue.number,
        owner: context.repo.owner,
        repo: context.repo.repo,
        body: comment
      });

Matrix Strategy

name: Lint CLAUDE.md files

on: [push, pull_request]

jobs:
  lint-claude:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        file: 
          - 'CLAUDE.md'
          - 'docs/CLAUDE.md'
          - 'api/CLAUDE.md'
    
    steps:
    - uses: actions/checkout@v4
    
    - name: Lint ${{ matrix.file }}
      uses: felixgeelhaar/cclint@v0.1.2
      with:
        files: ${{ matrix.file }}
        format: 'text'

Integration with Other Actions

name: Comprehensive Check

on: [push, pull_request]

jobs:
  check:
    runs-on: ubuntu-latest
    
    steps:
    - uses: actions/checkout@v4
    
    # Install dependencies
    - name: Setup Node.js
      uses: actions/setup-node@v4
      with:
        node-version: '20'
        cache: 'npm'
    
    - name: Install dependencies
      run: npm ci
    
    # Run tests
    - name: Run tests
      run: npm test
    
    # Lint code
    - name: Lint TypeScript
      run: npm run lint
    
    # Lint CLAUDE.md
    - name: Lint CLAUDE.md
      uses: felixgeelhaar/cclint@v0.1.2
      with:
        files: 'CLAUDE.md'
        format: 'text'
        fail-on-error: 'true'
    
    # Build project
    - name: Build
      run: npm run build

Alternative: Manual Installation

If you prefer to install cclint manually in your workflow:

- name: Setup Node.js
  uses: actions/setup-node@v4
  with:
    node-version: '20'
    
- name: Install cclint
  run: npm install -g cclint
  
- name: Lint CLAUDE.md
  run: cclint lint CLAUDE.md --format json > lint-results.json
  
- name: Upload results
  uses: actions/upload-artifact@v4
  with:
    name: lint-results
    path: lint-results.json

Troubleshooting

Action Not Found

Make sure you're using the correct version tag:

uses: felixgeelhaar/cclint@v0.1.2  # ✅ Correct
uses: felixgeelhaar/cclint@main    # ❌ Incorrect

No Files Found

Check your glob patterns and make sure files exist:

- name: List files before linting
  run: find . -name "CLAUDE.md" -type f

- name: Lint CLAUDE.md
  uses: felixgeelhaar/cclint@v0.1.2
  with:
    files: 'CLAUDE.md'

Permission Issues

Make sure the action has proper permissions:

permissions:
  contents: read
  pull-requests: write  # If commenting on PRs

Best Practices

  1. Pin to specific version: Use @v0.1.2 instead of @main
  2. Use meaningful job names: Help identify failures quickly
  3. Cache when possible: Cache Node.js dependencies for faster runs
  4. Fail fast: Use fail-on-error: true to catch issues early
  5. Provide feedback: Use outputs to comment on PRs with results