Agile Metrics Action

A GitHub Action that collects key agile and DevOps metrics from your repository, including:

DORA Metrics:

• Deploy Frequency: How often deployments are made to production
• Cycle Time: Time from commit to deployment

DevEx Metrics:

• PR Size: Automatic categorization of pull request size with labels and comments
• PR Maturity: Ratio of stable code vs changes made after PR publication

Team Metrics:

• Pickup Time: Time from PR creation to first review
• Approve Time: Time from first comment to approval
• Merge Time: Time from approval to merge
• Merge Frequency: Number of PRs merged per developer per week

Features

DORA Metrics:

• 🚀 Automatic Detection: Prioritizes GitHub releases over tags for metrics calculation
• 📊 Comprehensive Metrics: Calculates average, oldest, and newest lead times
• 🔧 Configurable: Supports various options for different workflows

DevEx Metrics:

• 🏷️ PR Size Labeling: Automatically adds size labels (size/xs, size/s, size/m, size/l, size/xl)
• 💬 PR Comments: Adds informative comments with detailed size breakdown
• 🎯 PR Maturity Analysis: Measures code stability after PR publication
• 🔍 Smart Filtering: Ignore specific files, line deletions, or file deletions
• 📐 Flexible Sizing: Configurable thresholds for different project needs

Team Metrics:

• 📊 Aggregate Analytics: Team-wide metrics across multiple PRs over time
• ⏱️ Time Tracking: Pickup, approve, and merge time measurements
• 🚀 Velocity Insights: Merge frequency per developer metrics
• 📈 Trend Analysis: Weekly, fortnightly, or monthly reporting periods
• 🎯 Performance Ratings: Elite/Good/Fair/Needs Focus classifications
• 📝 Rich Reports: Markdown reports with statistics and visualizations

General:

• 📝 Rich Output: Provides JSON data, individual metrics, and Markdown summaries
• 🔄 Git Integration: Optionally commits metrics back to the repository
• ⚡ Fast & Reliable: Built with robust error handling and performance optimization
• 🔀 Independent Metrics: Each metric can be enabled/disabled individually for maximum flexibility

Usage

Basic Usage

Deploy Frequency Metric

name: Collect Deploy Frequency

on:
  schedule:
    - cron: '0 9 * * 1' # Every Monday at 9 AM UTC
  workflow_dispatch:

jobs:
  metrics:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Collect Deploy Frequency
        uses: rdytech/agile-metrics-action@v2
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          deployment-frequency: 'true'

Cycle Time Metric

name: Collect Cycle Time

on:
  schedule:
    - cron: '0 9 * * 1' # Every Monday at 9 AM UTC
  workflow_dispatch:

jobs:
  metrics:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Collect Cycle Time
        uses: rdytech/agile-metrics-action@v2
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          lead-time: 'true'

PR Size Analysis

name: PR Size Analysis

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  pr-size:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Analyze PR Size
        uses: rdytech/agile-metrics-action@v2
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          pr-size: 'true'
          files-to-ignore: '*.md,*.txt,package-lock.json'
          ignore-line-deletions: 'false'

PR Maturity Analysis

name: PR Maturity Analysis

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  pr-maturity:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Analyze PR Maturity
        uses: rdytech/agile-metrics-action@v2
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          pr-maturity: 'true'

Advanced Configuration

Team Metrics

name: Collect Team Metrics

on:
  schedule:
    - cron: '0 9 * * 1' # Every Monday at 9 AM UTC
  workflow_dispatch:

jobs:
  team-metrics:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Collect Team Metrics
        uses: rdytech/agile-metrics-action@v2
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          team-metrics: 'true'
          time-period: 'weekly' # Options: weekly, fortnightly, monthly
          team-metrics-output-path: 'reports/team_metrics.md'

Inputs

General Inputs

Input	Description	Required	Default
github-token	GitHub token for API access	✅	${{ github.token }}
output-path	Path where metrics JSON file is saved	❌	metrics/delivery_metrics.json
commit-results	Commit the metrics file to repository	❌	true

Metric-Specific Inputs

Input	Description	Required	Default
deployment-frequency	Enable deploy frequency metric	❌	false
lead-time	Enable cycle time metric	❌	false
pr-size	Enable PR size metric	❌	false
pr-maturity	Enable PR maturity metric	❌	false
team-metrics	Enable team metrics	❌	false

Team Metrics Configuration

Applies to team-metrics metric.

Input	Description	Required	Default
time-period	Time period (weekly/fortnightly)	❌	weekly
team-metrics-output-path	Path for team metrics report	❌	metrics/team_metrics_report.md

DORA Metrics Configuration

Applies to deployment-frequency and lead-time metrics.

Input	Description	Required	Default
include-merge-commits	Include merges in cycle time	❌	false
max-releases	Max releases to fetch for analysis	❌	100
max-tags	Max tags if no releases found	❌	100

DevEx Metrics Configuration

Applies to pr-size and pr-maturity metrics.

Input	Description	Required	Default
files-to-ignore	File patterns to ignore (comma)	❌	""
ignore-line-deletions	Ignore line deletions in PR size	❌	false
ignore-file-deletions	Ignore file deletions in PR size	❌	false

Outputs

General Outputs

Output	Description
metrics-json	Complete metrics data as JSON string
metrics-file-path	Path to the generated metrics file

DORA Metrics Outputs

Output	Description
deployment-frequency	Days between latest and previous deployment
lead-time-avg	Average cycle time in hours
lead-time-oldest	Oldest commit cycle time in hours
lead-time-newest	Newest commit cycle time in hours
commit-count	Number of commits analyzed

DevEx Metrics Outputs

Output	Description
pr-size	PR size category (xs, s, m, l, xl)
pr-size-category	PR size with prefix (size/xs, etc.)
pr-size-details	Detailed PR size metrics as JSON
pr-maturity-ratio	PR maturity ratio (0.0 to 1.0)
pr-maturity-percentage	PR maturity percentage (0 to 100)
pr-maturity-details	Detailed PR maturity metrics as JSON

Team Metrics Outputs

Output	Description
team-metrics-json	Team metrics data as JSON
team-metrics-report-path	Path to team metrics markdown

Metrics Explained

DORA Metrics

Deploy Frequency

Measures how often your team deploys code to production. Calculated as the time difference between consecutive releases or tags.

Cycle Time

Time from when a commit is made to when it's deployed to production. Helps identify bottlenecks in your delivery pipeline.

DevEx Metrics

PR Size

Automatically categorizes pull requests based on the total number of changes (additions + deletions):

• S (🔹): < 105 changes - Small features, bug fixes
• M (🔸): 106-160 changes - Medium features, refactoring
• L (🔶): 161-240 changes - Large features, significant changes
• XL (🔥): > 240 changes - Major refactoring, multiple features

Benefits:

• Encourages smaller, more reviewable PRs
• Provides visibility into PR complexity
• Helps with review planning and resource allocation
• Supports better development practices

Filtering Options:

• files-to-ignore: Skip files that don't impact complexity (e.g., *.md, package-lock.json)
• ignore-line-deletions: Focus only on additions when appropriate
• ignore-file-deletions: Exclude deleted files from size calculation

PR Maturity

Measures the stability of code when a pull request is initially published by calculating the ratio between stable changes (initial commit) and total changes added after publication.

Calculation:

• Maturity Ratio: stable_changes / total_changes
• Maturity Percentage: Ratio converted to percentage (0-100%)

Maturity Levels:

• ⭐ Elite (>88%): Highest stability, minimal changes after publication
• ✅ Good (81-87%): Strong stability with minor adjustments
• ⚖️ Fair (75-80%): Moderate stability, some adjustments needed
• 🎯 Needs Focus (<75%): Significant changes after publication

Benefits:

• Encourages better preparation before PR publication
• Identifies patterns of incomplete or rushed development
• Helps teams improve their development workflow
• Provides insights into code quality and review processes

Use Cases:

• Track improvement in development practices over time
• Identify developers who might need additional support
• Measure the effectiveness of code review processes
• Monitor the stability of feature development

Team Performance Metrics

Team metrics provide aggregated insights across multiple PRs over a specified time period, helping teams understand their development velocity and quality patterns.

Metrics Collected:

• Pickup Time: Time from PR creation to first review activity
• Approve Time: Time from first comment to first approval
• Merge Time: Time from first approval to merge
• Merge Frequency: Number of merged PRs per developer per week

Time Periods:

• Weekly: Last 7 days
• Fortnightly: Last 14 days
• Monthly: Last 30 days

Rating Levels:

All time-based metrics are rated on the same 4-level scale:

Level	Pickup	Approve	Merge	Frequency
⭐ Elite	< 2h	< 17h	< 2h	> 1.6 PRs/dev/week
✅ Good	2-6h	17-24h	2-5h	1.1-1.6 PRs/dev/week
⚖️ Fair	7-16h	25-45h	6-19h	0.6-1.0 PRs/dev/week
🎯 Needs Focus	> 16h	> 45h	> 19h	< 0.6 PRs/dev/week

Outputs:

• JSON data with all metrics and per-PR details
• Markdown report with statistics and ratings
• GitHub Actions summary for immediate visibility

Benefits:

• Identifies bottlenecks in the review process
• Tracks team velocity and throughput
• Measures code review effectiveness
• Highlights areas for process improvement
• Provides data-driven insights for retrospectives

How It Works

1. Data Source Detection: The action first looks for GitHub releases, then falls back to tags if no releases are found
2. Release Analysis: Compares the latest and previous releases/tags to calculate deployment frequency
3. Commit Analysis: Examines all commits between releases to calculate lead time for changes
4. Output Generation: Creates JSON file, sets GitHub Actions outputs, and generates markdown summary
5. Optional Commit: Can commit the metrics file back to the repository for tracking over time

Output Format

The action generates a comprehensive JSON file with the following structure:

{
  "generated_at": "2023-01-01T12:00:00.000Z",
  "repo": "owner/repo",
  "source": "release",
  "latest": {
    "name": "v2.0.0",
    "tag": "v2.0.0",
    "sha": "abc123",
    "created_at": "2023-01-01T12:00:00.000Z"
  },
  "previous": {
    "name": "v1.0.0",
    "tag": "v1.0.0",
    "sha": "def456",
    "created_at": "2022-12-25T12:00:00.000Z"
  },
  "metrics": {
    "dora": {
      "deploy_frequency_days": 7,
      "cycle_time": {
        "commit_count": 15,
        "avg_hours": 24.5,
        "oldest_hours": 72.0,
        "newest_hours": 2.5,
        "oldest_commit_sha": "old123",
        "newest_commit_sha": "new456",
        "newest_excludes_merges": true
      }
    }
  }
}

Contributing

1. Install dependencies: npm install
2. Run tests: npm test
3. Bundle the action: npm run bundle
4. Create a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Migration Guide

v2.x Configuration

- uses: rdytech/agile-metrics-action@v2
  with:
    deployment-frequency: 'true'
    lead-time: 'true'
    pr-size: 'true'
    pr-maturity: 'true'

v2.x Configuration

Added team-metrics, time-period and team-metrics-output-path.

- uses: rdytech/agile-metrics-action@v2
  with:
    team-metrics: 'true'
    time-period: ${{ inputs.time-period || 'monthly' }}
    team-metrics-output-path: reports/team_metrics.md