Devscope GitHub Action

Zero-config code health checks for your pull requests 🚀

Automatically analyze your repository and post maintainability metrics on every PR. No configuration needed — just drop it in your workflow.

---

� Why Devscope in CI?

Shift-left code quality — catch maintainability issues before they reach production.

• ✅ Instant feedback — developers see health metrics within seconds on PRs
• ✅ Preventative maintenance — block merges when quality drops below thresholds
• ✅ No configuration required — works out of the box with sensible defaults
• ✅ Language agnostic — analyzes Python, JavaScript, TypeScript, Go, Rust, Java, and more
• ✅ Fast & cached — pipx dependencies cached between runs (~5-8s after first run)
• ✅ Non-intrusive — sticky PR comments (updates in place, no spam)

Use cases:

• Enforce maintainability standards across teams
• Monitor tech debt trends in CI
• Gate releases on code health thresholds
• Onboard new contributors with clear quality metrics

---

�🎯 Features

• ✅ Automatic PR comments with health metrics
• ✅ Sticky updates — no comment spam
• ✅ CI quality gates with configurable thresholds
• ✅ Fast caching — pipx packages cached between runs
• ✅ Rich outputs — use metrics in other workflow steps
• ✅ Zero config — works out of the box

---

🚀 Quick Start

Basic PR Health Check

Add this to .github/workflows/devscope.yml:

name: Code Health

on:
  pull_request:
  push:
    branches: [main]

jobs:
  health-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Full history for git metrics
      
      - uses: EhsanAzish80/devscope-action@v1

That's it! 🎉

Example PR Comment:

📊 Devscope Report

Maintainability: 🟢 B
Risk: 🟢 Low
Onboarding: Easy
⚡ 0.82s

<details>
<summary>Full summary ▼</summary>

───────────────────────────────────────
Devscope: B · Low risk · Easy onboarding · 0.78 tests · 0.82s ⚡

Files: 1,247
Lines: 45,892
Languages: Python (45%) · TypeScript (33%) · JavaScript (12%)

**Metrics:**
- Maintainability Grade: B (82.5/100)
- Risk Level: Low
- Onboarding Difficulty: Easy
- Test Coverage: 78%

Analyze your repo → `pipx install devscope`
Updated: Thu, 13 Feb 2026 15:30:00 GMT
</details>

Features:

• ✅ Emoji indicators 🟢 green (good), 🔴 red (critical)
• ✅ Sticky updates (edits same comment, no spam)
• ✅ Collapsible full summary
• ✅ Performance timing

---

📖 Usage Examples

With CI Quality Gate

Fail the workflow if maintainability drops below B:

- uses: EhsanAzish80/devscope-action@v1
  with:
    fail-under: B
    max-risk: Medium
    max-onboarding: Moderate

Exit codes:

• 0 = All thresholds passed
• 1 = Runtime error
• 2 = Threshold violated (fails CI)

Analyze Specific Directory

- uses: EhsanAzish80/devscope-action@v1
  with:
    path: ./src

Use Outputs in Other Steps

- uses: EhsanAzish80/devscope-action@v1
  id: devscope

- name: Check grade
  run: |
    echo "Grade: ${{ steps.devscope.outputs.grade }}"
    echo "Risk: ${{ steps.devscope.outputs.risk }}"
    
    if [ "${{ steps.devscope.outputs.grade }}" == "F" ]; then
      echo "::warning::Code health is critical!"
    fi

Custom GitHub Token

For private repos or fine-grained permissions:

- uses: EhsanAzish80/devscope-action@v1
  with:
    github-token: ${{ secrets.CUSTOM_PAT }}

---

🔧 Configuration

Inputs

Input	Description	Default	Required
path	Directory to analyze	.	No
fail-under	Minimum grade (A, B, C, D, F)	(none)	No
max-risk	Maximum risk level (Low, Medium, High)	(none)	No
max-onboarding	Max onboarding difficulty (Easy, Moderate, Hard)	(none)	No
github-token	GitHub token for PR comments	${{ github.token }}	No

Outputs

Output	Description	Example
health	Overall health score (0-100)	82.5
risk	Risk level	Low
onboarding	Onboarding difficulty	Easy
grade	Maintainability grade	B

---

🎨 PR Comment Format

The action posts a beautifully formatted comment on PRs:

Collapsed view:

📊 Devscope Report

Maintainability: 🟢 B
Risk: 🟢 Low
Onboarding: Easy
⚡ 0.82s

Expanded view:

📊 Devscope Report

Maintainability: 🟢 B
Risk: 🟢 Low
Onboarding: Easy
⚡ 0.82s

Full summary ▼
───────────────────────────────────────
Devscope: B · Low risk · Easy onboarding · 0.78 tests · 0.82s ⚡

Files: 1,247
Lines: 45,892
Languages: Python (45%) · TypeScript (33%) · JavaScript (12%)

Analyze your repo → pipx install devscope
Updated: Thu, 13 Feb 2026 15:30:00 GMT

Features:

• ✅ Emoji indicators (🟢 green = good, 🔴 red = bad)
• ✅ Sticky updates (same comment, no spam)
• ✅ Collapsible full summary
• ✅ Timestamp tracking

---

📊 Example Workflows

Full CI/CD Pipeline

name: Code Quality

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

jobs:
  health-check:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Required for git metrics
      
      - name: Run Devscope
        uses: EhsanAzish80/devscope-action@v1
        id: devscope
        with:
          fail-under: B
          max-risk: Medium
      
      - name: Upload metrics
        if: always()
        run: |
          echo "Health: ${{ steps.devscope.outputs.health }}"
          echo "Grade: ${{ steps.devscope.outputs.grade }}"
          echo "Risk: ${{ steps.devscope.outputs.risk }}"

Monorepo (Multiple Directories)

jobs:
  health-check:
    strategy:
      matrix:
        service: [frontend, backend, shared]
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      
      - uses: EhsanAzish80/devscope-action@v1
        with:
          path: ./services/${{ matrix.service }}
          fail-under: C

Different Thresholds by Branch

- uses: EhsanAzish80/devscope-action@v1
  with:
    fail-under: ${{ github.ref == 'refs/heads/main' && 'A' || 'B' }}
    max-risk: ${{ github.ref == 'refs/heads/main' && 'Low' || 'Medium' }}

---

⚡ Performance

This action uses aggressive caching for fast runs:

Phase	First Run	Cached Runs
Setup Python	~5s	~2s (cached)
Install devscope	~10-15s	~3-5s (pipx cache)
Analysis	~0.5-2s	~0.5-2s
Total	~15-20s	~5-8s ⚡

Optimization tips:

• Use fetch-depth: 0 for accurate git metrics
• Enable pipx caching (automatic in this action)
• Run on push + PR for best cache hits

Most runs complete in under 10 seconds after initial setup ⚡

---

🔒 Permissions

Required Permissions

permissions:
  contents: read          # Read repository code
  pull-requests: write    # Post PR comments

Minimal setup:

jobs:
  health-check:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      - uses: EhsanAzish80/devscope-action@v1

For Forks

If you want to support PRs from forks:

on:
  pull_request_target:  # Use with caution!

permissions:
  contents: read
  pull-requests: write

⚠️ Security note: pull_request_target runs with write access. Only use if you trust fork contributors or implement additional checks.

---

🐛 Troubleshooting

Comment not appearing on PR

Check permissions:

permissions:
  pull-requests: write

Verify trigger:

on:
  pull_request:  # Must include this

Action fails with "command not found: devscope"

The action installs devscope automatically. If it fails:

1. Check Python version (requires 3.9+)
2. Clear cache: Go to Actions → Caches → Delete all caches
3. Re-run workflow

Thresholds not enforced

Thresholds only apply on push events, not PRs. PRs show metrics but don't fail.

To enforce on PRs:

on:
  pull_request:
  push:
    branches: [main]

Slow analysis

Enable caching:

- uses: actions/checkout@v4
  with:
    fetch-depth: 0  # Faster git operations

---

🔄 Versioning

This action follows semantic versioning:

• @v1 — Latest v1.x.x (recommended, auto-updates)
• @v1.0.0 — Exact version (pinned, no updates)
• @main — Latest commit (unstable, for testing)

Recommended:

- uses: EhsanAzish80/devscope-action@v1

---

📦 What's Included

This action:

• Installs devscope via pipx
• Caches Python dependencies for speed
• Analyzes your codebase (Python, JS, TS, Go, Rust, Java, etc.)
• Posts formatted PR comments
• Enforces quality gates on push events
• Provides structured outputs for custom workflows

---

🤝 Contributing

Contributions welcome! Please:

1. Fork the repo
2. Create a feature branch
3. Test locally with act
4. Submit a PR

Local testing:

# Install act
brew install act

# Test workflow
act pull_request -j health-check

---

📄 License

MIT License - see LICENSE file.

---

🙏 Acknowledgments

Built with:

• devscope — The analysis engine
• actions/github-script — PR comment management
• actions/setup-python — Python setup with caching

---

📞 Support

• 🐛 Report a bug
• 💡 Request a feature
• 💬 Discussions

---