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 Healthon:
pull_request:
push:
branches: [main]jobs:
health-check:
runs-on: ubuntu-lateststeps:
- uses: actions/checkout@v4with:
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@v1with:
fail-under: Bmax-risk: Mediummax-onboarding: Moderate

Exit codes:

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

Analyze Specific Directory

- uses: EhsanAzish80/devscope-action@v1with:
path: ./src

Use Outputs in Other Steps

- uses: EhsanAzish80/devscope-action@v1id: devscope
- name: Check graderun: | 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@v1with:
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 Qualityon:
pull_request:
push:
branches: [main, develop]jobs:
health-check:
runs-on: ubuntu-latestpermissions:
contents: readpull-requests: writesteps:
- name: Checkout codeuses: actions/checkout@v4with:
fetch-depth: 0# Required for git metrics
- name: Run Devscopeuses: EhsanAzish80/devscope-action@v1id: devscopewith:
fail-under: Bmax-risk: Medium
- name: Upload metricsif: 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-lateststeps:
- uses: actions/checkout@v4with:
fetch-depth: 0
- uses: EhsanAzish80/devscope-action@v1with:
path: ./services/${{ matrix.service }}fail-under: C

Different Thresholds by Branch

- uses: EhsanAzish80/devscope-action@v1with:
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 codepull-requests: write # Post PR comments

Minimal setup:

jobs:
health-check:
runs-on: ubuntu-latestpermissions:
contents: readpull-requests: writesteps:
- 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: readpull-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@v4with:
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

---