AI Slop Badge Action

Run aislop, write a Shields endpoint badge JSON file, and optionally commit the badge source back to your repository.

This action is a composite action with no build step. It works well as a drop-in replacement for a hand-written scan workflow when you want a README badge that shows the numeric AI slop score.

Quick Start

1. Add the aislop action to your workflow.
2. Add the README badge shown below.
3. Push to main once so the badge JSON exists at the raw GitHub URL.

name: AI Slop Badge

on:
  push:
    branches:
      - main
    paths-ignore:
      - ".github/badges/aislop-score.json"
  pull_request:
    branches:
      - main
  workflow_dispatch:

permissions:
  contents: write

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

      - uses: actions/setup-node@v4
        with:
          node-version: 22

      - id: badge
        uses: sandwichfarm/aislop-badge@v1
        with:
          badge-file: .github/badges/aislop-score.json
          commit-badge: ${{ github.event_name != 'pull_request' && github.ref == 'refs/heads/main' }}

Add this badge to README.md after the first successful main run:

[![AI Slop Score](https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2FOWNER%2FREPO%2Fmain%2F.github%2Fbadges%2Faislop-score.json)](https://github.com/sandwichfarm/REPO/actions/workflows/aislop-badge.yml)

Replace sandwichfarm, REPO, and main with your repository values. The url= value is URL-encoded because Shields fetches the JSON badge source from raw GitHub content.

Configuration

Input	Default	Description
scan-path	.	Path passed to aislop scan --json.
aislop-version	0.9.3	npm package version used for the scan.
package-runner	npx	Runner for the isolated CLI install. Supported: npx, pnpm, bunx.
badge-file	.github/badges/aislop-score.json	Shields endpoint JSON file to write.
badge-label	ai slop	Badge label.
badge-message-template	{score}/100 {label}	Badge message. Tokens: {score}, {label}, {errors}, {warnings}, {fixable}.
badge-color	empty	Color override. Empty chooses color from score: 90+ brightgreen, 80+ green, 70+ yellowgreen, 60+ yellow, 50+ orange, below 50 red.
minimum-score	0	Fail when score is below this value. 0 disables this threshold.
fail-on-error	true	Fail when the aislop command exits non-zero.
commit-badge	false	Commit badge-file when it changes. Use an expression to enable this only on main.
push	true	Push the badge commit. Used only when commit-badge is true.
commit-message	chore: update AI slop score badge [skip ci]	Commit message for badge updates.
git-user-name	github-actions[bot]	Git author name for badge updates.
git-user-email	41898282+github-actions[bot]@users.noreply.github.com	Git author email for badge updates.
summary	true	Write score, issue counts, and badge path to the workflow summary.

Outputs

Output	Description
score	Numeric aislop score.
label	aislop score label.
color	Badge color used in the JSON file.
errors	Number of errors from the scan summary.
warnings	Number of warnings from the scan summary.
fixable	Number of fixable issues from the scan summary.
report-file	Path to the raw aislop JSON report.
badge-file	Path to the generated Shields endpoint JSON file.
exit-code	Exit code returned by aislop.
meets-minimum	true when score >= minimum-score.
badge-updated	true when this action created a badge commit.
commit-sha	SHA of the badge commit, when one was created.

Common Setups

Scan Only

Use this when you want the score as workflow outputs but do not want a README badge commit.

- id: aislop
  uses: sandwichfarm/aislop-badge@v1
  with:
    commit-badge: false

Require a Minimum Score

- uses: sandwichfarm/aislop-badge@v1
  with:
    minimum-score: 85

Use pnpm Instead of npx

- uses: sandwichfarm/aislop-badge@v1
  with:
    package-runner: pnpm

Commit the Badge Only on Main

- uses: sandwichfarm/aislop-badge@v1
  with:
    commit-badge: ${{ github.event_name != 'pull_request' && github.ref == 'refs/heads/main' }}

Permissions

For scan-only usage, read permission is enough:

permissions:
  contents: read

For automatic badge commits, the workflow needs write permission:

permissions:
  contents: write

Keep commit-badge disabled for pull requests. That avoids trying to push from untrusted PR contexts and keeps the PR token read-only in normal setups.

Badge JSON

The generated file is compatible with Shields endpoint badges:

{
  "schemaVersion": 1,
  "label": "ai slop",
  "message": "89/100 Healthy",
  "color": "green"
}