Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .mise.toml
Original file line number Diff line number Diff line change
Expand Up @@ -32,4 +32,5 @@ run = [
"bash ./tests/open-pr-labels.sh",
"bash ./tests/config-sync-ai-toolkit-instructions.sh",
"python3 ./tests/workflow-job-conditions.py",
"python3 ./tests/ai-commits-badge.py",
]
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ repositories.
| ---------------------------- | ----------------------------------------------------------------------------------------- |
| Reusable workflows | [`.github/workflows/`](.github/workflows/) |
| Composite actions | [`actions/`](actions/) |
| AI commits badge | [`actions/ai-commits-badge/`](actions/ai-commits-badge/README.md) |
| Workflow templates | [`workflow-templates/`](workflow-templates/) |
| Config sync (files) | [`config-sync/files/`](config-sync/files/) |
| Config sync (templates) | [`config-sync/templates/`](config-sync/templates/) |
Expand Down
217 changes: 217 additions & 0 deletions actions/ai-commits-badge/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,217 @@
# `ai-commits-badge` composite action

Generate an AI commits badge and README card from Git history. No git-ai,
third-party actions, Python packages, network calls or publishing are needed.
Run on Linux with Bash, Git and Python 3.8+ already available.

## What it measures

Each non-merge commit is classified once, in this order:

1. **AI agent:** its author matches a bundled AI identity.
2. **Bot automation:** its author contains `[bot]`, unless recognized above.
Excluded from the denominator, including bot commits with AI trailers.
3. **Co-authored with AI:** a `Co-authored-by` trailer matches an AI identity.
4. **No recorded AI attribution:** neither author nor trailers match.

The percentage is `(agent + coauthored) / (agent + coauthored + unattributed)`.
This counts commits, not lines, effort or the percentage of code written by AI.
Missing attribution is **not proof of human authorship**. Squashing, lost
trailers and unrecognized tools affect the result. Tool counts use the first
matching identity, not every co-author. Defaults recognize Copilot, Claude,
Cursor, Devin, Jules and Aider; the exact rules live in
[`ai_commits_badge.py`](ai_commits_badge.py).

The card legend shortens the final category to **No recorded AI** to fit its
existing 480px layout. Tooltips and accessible hover text retain the full
**No recorded AI attribution** wording. The corresponding machine-readable
key and action output are `unattributed`.

Long repository names are clipped to the card's 200px header region without
stretching the text. The full name remains in the tooltip and accessible text.

## Inputs

| Input | Default | Meaning |
| ---------- | -------------------------- | --------------------------------------------------------------- |
| `ref` | `HEAD` | Commit, branch or tag reachable in the local checkout. |
| `since` | empty | Optional Git date filter, e.g. `90 days ago`. |
| `name` | `${{ github.repository }}` | Name displayed on the card and in tooltips. |
| `label` | `AI commits` | Compact badge and Shields endpoint label. |
| `out` | `badges` | Output directory relative to the caller's working directory. |
| `themes` | `"false"` | Set `"true"` to also write light/dark cards. Other values fail. |
| `repo-dir` | `.` | Checkout to measure; the action never changes it. |

Identity rules are centralized and cannot be overridden per caller, so repos
using the same action revision use comparable classification rules. Add new
AI identities to the bundled list through a PR in this repository. The same
case-insensitive rules match complete recognized names or email addresses for
authors and individual trailers. Email patterns include the expected domain;
partial names and addresses do not establish AI attribution.

## Outputs and files

| Step output | Meaning |
| --------------------- | --------------------------------------------------------- |
| `ai-percent` | One-decimal percentage, or `n/a` when no commits qualify. |
| `commits` | Denominator, excluding merge and automation commits. |
| `ai-commits` | Agent-authored plus AI-co-authored commits. |
| `agent` | AI-authored commits. |
| `coauthored` | AI-co-authored commits. |
| `unattributed` | No recorded AI attribution. |
| `excluded-automation` | Excluded non-merge bot commits. |

The badge displays a whole-number percentage calculated directly from the
commit counts; `ai-percent` and stats JSON retain one decimal. Display values
are not rounded again from the statistics. Empty history produces a grey
`n/a` badge.

| File in `out` | Purpose |
| ------------------------------------------------------- | ----------------------------------------------------------------- |
| `ai-commits.svg` | Compact badge with a proportional strip and hover breakdown. |
| `ai-commits.json` | Shields.io endpoint JSON (`schemaVersion: 1`). |
| `ai-commits-stats.json` | Counts, tool breakdown, ref, date filter and UTC generation time. |
| `ai-commits-card.svg` | Card following `prefers-color-scheme`. |
| `ai-commits-card-light.svg`, `ai-commits-card-dark.svg` | Additional cards when `themes: "true"`. |

The action writes files only. Callers own uploads, branch updates, permissions,
retention and publication. Counts and tool names become visible wherever you
publish these files. Publishing results from private or work repositories is a
separate, explicitly approved decision for each repository owner.

## Complete history is required

Use `actions/checkout` with `fetch-depth: 0`. The default shallow checkout fails
with an actionable message before writing files or step outputs; `since` does
not bypass this guard. The action never fetches history automatically.
Fetch any requested non-default ref in the caller as well.

## Example: add badges to a MkDocs site

In the docs workflow, add a daily refresh and generate **after** `mkdocs build`
(which cleans `site`) and **before** uploading the Pages artifact. Keep your
existing pinned MkDocs setup/build steps and Pages deployment configuration.

```yaml
---
name: Docs
on:
push:
branches: [main]
workflow_dispatch:
schedule:
- cron: "17 4 * * *"
permissions:
contents: read

jobs:
build:
runs-on: ubuntu-24.04
steps:
# renovate: datasource=github-tags depName=actions/checkout
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
fetch-depth: 0
persist-credentials: false
# Keep the site's existing pinned toolchain setup here.
- run: mkdocs build
- uses: DevSecNinja/.github/actions/ai-commits-badge@<release-commit-sha>
id: ai
with:
out: site/badges
themes: "true"
- run: printf 'AI commits %s/%s (%s%%)\n' "$AI" "$TOTAL" "$PERCENT"
env:
AI: ${{ steps.ai.outputs.ai-commits }}
TOTAL: ${{ steps.ai.outputs.commits }}
PERCENT: ${{ steps.ai.outputs.ai-percent }}
# renovate: datasource=github-tags depName=actions/upload-pages-artifact
- uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
with:
path: site
```

The snippet assumes MkDocs is already installed by your existing docs setup.
Keep the existing Pages deploy job after `build`, with `pages: write` and
`id-token: write`. The daily trigger regenerates rolling `since` windows even
when the source has no new commits.

In a README, reference the published site, for example:

```markdown
[![AI commits](https://example.org/badges/ai-commits.svg)](https://example.org/badges/ai-commits-stats.json)
```

Or use Shields with the publicly accessible, URL-encoded JSON endpoint:
`https://img.shields.io/endpoint?url=https%3A%2F%2Fexample.org%2Fbadges%2Fai-commits.json`.

## Example: standalone badge-only Pages site

For a repo without documentation, publish just the generated files to Pages.
Configure its Pages source as **GitHub Actions** first. This avoids committing
generated artifacts or needing a separate `badges` branch.

```yaml
---
name: Badges
on:
push:
branches: [main]
workflow_dispatch:
schedule:
- cron: "17 4 * * *"
permissions:
contents: read
concurrency:
group: badges-pages
cancel-in-progress: false

jobs:
publish:
runs-on: ubuntu-24.04
permissions:
contents: read
pages: write
id-token: write
environment:
name: github-pages
url: ${{ steps.deploy.outputs.page_url }}
steps:
# renovate: datasource=github-tags depName=actions/checkout
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
fetch-depth: 0
persist-credentials: false
- uses: DevSecNinja/.github/actions/ai-commits-badge@<release-commit-sha>
with:
out: public/badges
themes: "true"
# renovate: datasource=github-tags depName=actions/upload-pages-artifact
- uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
with:
path: public
# renovate: datasource=github-tags depName=actions/deploy-pages
- uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1
id: deploy
```

For a project site, the badge URL is
`https://OWNER.github.io/REPO/badges/ai-commits.svg`.
Do not use this workflow alongside another Pages site in the same repo: it
would replace that deployment. Use the docs-site pattern instead.

Both examples intentionally leave the new action's ref as
`<release-commit-sha>` until it is released. Replace it with the released full
40-character SHA and a version comment before use; let Renovate track the
release as with other centralized actions.

## Local checks

```sh
python3 tests/ai-commits-badge.py
python3 actions/ai-commits-badge/ai_commits_badge.py \
--repo-dir . --ref HEAD --out /tmp/ai-badges --themes
```

The tests build isolated synthetic Git history and execute the composite
action's actual Bash step, including its environment wiring and outputs.
82 changes: 82 additions & 0 deletions actions/ai-commits-badge/action.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
---
name: AI commits badge
description: Generate README badges from commit authors and recorded AI co-authorship, excluding merges and automation bots.
inputs:
ref:
description: "Commit, branch or tag to measure."
default: HEAD
since:
description: "Optional git date filter, for example 90 days ago."
default: ""
name:
description: "Repository name shown in the card and tooltip."
default: ${{ github.repository }}
label:
description: "Compact badge and Shields endpoint label."
default: AI commits
out:
description: "Output directory, relative to the caller's working directory."
default: badges
themes:
description: "Also generate separate light and dark cards (true or false)."
default: "false"
repo-dir:
description: "Repository to measure. Must have complete history."
default: "."
outputs:
ai-percent:
description: "AI share of considered commits, rounded to one decimal; n/a for an empty denominator."
value: ${{ steps.generate.outputs.ai-percent }}
commits:
description: "Non-merge commits excluding automation bots."
value: ${{ steps.generate.outputs.commits }}
ai-commits:
description: "Agent-authored plus AI-co-authored commits."
value: ${{ steps.generate.outputs.ai-commits }}
agent:
description: "Commits authored by a recognized AI identity."
value: ${{ steps.generate.outputs.agent }}
coauthored:
description: "Commits with a recognized AI Co-authored-by trailer."
value: ${{ steps.generate.outputs.coauthored }}
unattributed:
description: "Commits with no recorded AI attribution."
value: ${{ steps.generate.outputs.unattributed }}
excluded-automation:
description: "Excluded non-merge automation-bot commits."
value: ${{ steps.generate.outputs.excluded-automation }}
runs:
using: composite
steps:
- name: Generate AI commits badges
id: generate
shell: bash
env:
ACTION_PATH: ${{ github.action_path }}
BADGE_REF: ${{ inputs.ref }}
BADGE_SINCE: ${{ inputs.since }}
BADGE_NAME: ${{ inputs.name }}
BADGE_LABEL: ${{ inputs.label }}
BADGE_OUT: ${{ inputs.out }}
BADGE_THEMES: ${{ inputs.themes }}
BADGE_REPO_DIR: ${{ inputs.repo-dir }}
run: |-
set -euo pipefail
args=(
"--repo-dir=${BADGE_REPO_DIR}"
"--ref=${BADGE_REF}"
"--since=${BADGE_SINCE}"
"--name=${BADGE_NAME}"
"--label=${BADGE_LABEL}"
"--out=${BADGE_OUT}"
"--github-output=${GITHUB_OUTPUT}"
)
case "${BADGE_THEMES}" in
true) args+=(--themes) ;;
false) ;;
*)
echo "::error::themes must be true or false." >&2
exit 1
;;
esac
python3 "${ACTION_PATH}/ai_commits_badge.py" "${args[@]}"
Loading
Loading