Gate the line count of a repository's files with a per-file ratchet that
only tightens. Ceilings have per-type defaults, are configurable through
with:, and take per-folder overrides in the same with: block; records
live in one committed JSON file and are never raised. Opt-in tree
budgets also cap a folder's total line count.
The measurement and ratchet are ported from
Nitjsefnie/claudit's
scripts/ci/size_baseline.py, reshaped from a per-repository allowlist
into the type-and-folder policy below.
Save this workflow as .github/workflows/size-baseline.yml. Its push:
filter names both conventional default branches, main and master,
and its steps resolve the actual default branch at run time, so a
repository whose default branch is either edits nothing outside the
with: block. A default branch with any other name is added to that
branches: list; without it, pull requests are still checked but the
default branch gets no standalone push run. The action reference is consumed by commit SHA — a
tag is a moving pointer — so pin the release's commit and keep the
# vX.Y.Z comment beside it, as the block below does for the latest
release. The file may also be one a consumer's own workflow already calls
as a reusable workflow: the workflow_call trigger below makes that
adoption an overwrite of that file too.
name: size baseline
on:
pull_request:
push:
branches: [main, master]
workflow_call:
permissions:
contents: read
concurrency:
group: ${{ github.workflow == 'size baseline' && format('size-baseline-{0}', github.event_name == 'push' && format('{0}-{1}', github.ref, github.sha) || github.ref) || format('size-baseline-called-{0}', github.run_id) }}
cancel-in-progress: true
jobs:
size-baseline:
environment: ${{ github.event_name == 'push' && github.ref_type == 'branch' && github.ref_name == github.event.repository.default_branch && format('{0}-push', github.event.repository.default_branch) || '' }}
runs-on: ubuntu-latest
timeout-minutes: 10
steps:
- if: github.event_name == 'pull_request' || (github.event_name == 'push' && github.ref_type == 'branch' && github.ref_name == github.event.repository.default_branch)
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
ref: ${{ github.event.pull_request.head.sha || github.sha }}
fetch-depth: 0
persist-credentials: false
- if: github.event_name == 'pull_request' || (github.event_name == 'push' && github.ref_type == 'branch' && github.ref_name == github.event.repository.default_branch)
uses: Nitjsefnie-Actions/size-ratchet@dcd7bb5427ac951d7270bf493c2c12e749432d72 # v3.1.2
with:
ceilings: ''
overrides: ''
exclude: ''
unclassified: 'ignore'
records: '.github/size-baseline.json'
member: ''
mode: 'auto'
base-ref: ${{ github.event.pull_request.base.sha }}
stale: 'warn'
require-tight: 'false'
push-key: ${{ secrets.MASTER_PUSH_DEPLOY_KEY }}
tree-budgets: ''The with: block shows every input with its default. Omit it and a
bare uses: step behaves the same on these events. The gate's steps run
only on a pull request or a push to the repository's default branch,
resolved from the event at run time; on any other event the block runs
on — a push to main or master where that is not the default branch,
a called run whose caller event is neither — the job completes green
without measuring. A push to any other branch, or a tag, starts no run
of the block, so a pull request from any branch but main or
master carries only the pull request's run on its head commit, and a
reader taking the newest run on that commit reads the check. The
checkout selects the PR's head tree; full history supplies the PR base without retaining a
token. The action needs a Git checkout, bash and Python 3.15, which it
sets up itself; when that install fails twice, a minute apart, it warns
and runs on the runner's own python3 instead, failing the step if the
runner has none. It runs its runner under python3 -I: the standard
library and the action's own modules only, so nothing from the consumer's
tree is ever imported or executed, and there is no dependency to install
or pin.
auto checks a pull request against the base revision's records, and on
a push to the repository's actual default branch it tightens the records
over that tree and commits the result (see Records on the default
branch). A pull request need not tighten the entries it loosens: under
the default require-tight: 'false' that run names each loose entry as a
notice and passes, and it still fails on growth past a record. Other events, including pushes to
another branch that reach the action without the steps' if, fail
closed and name the event. A mode: check forced by editing the block
must supply base-ref when the event has no PR base SHA.
A consumer whose aggregate workflow calls
.github/workflows/size-baseline.yml with uses: adopts by saving the
block over that file. An environment secret has been observed to read
empty inside a workflow_call callee, so a called run is expected to
take the no-key path (see Records on the default branch); the block's
own push run is the one that commits. The size leg stays
inside the required aggregate. A called run sees the
caller's event: on the caller's pull_request it checks the pull
request, on a caller push to the default branch it measures that tree
and never fails on a loose record, and on any other caller event the job completes green without
measuring, so a fold that requires the calling job reports. A consumer
that calls the block also gets the block's own standalone run on a pull
request and on a push to main or master; on a pull request and on a
push to a default branch with either name, both run the same check on
the same tree. The push: filter binds only that standalone run, the
one that commits the records: a default branch named neither main nor
master is added to its branches: list. A standalone pull request
run shares its group with that pull request's earlier run and replaces
a superseded one. A standalone push run's group is its branch and
commit, so the run the action's own records commit starts cancels
neither the run that pushed it nor an earlier commit's run, running or
pending; an older push run whose records push is then refused passes
once a fresh read shows the branch moved (see Records on the default
branch). A called run takes the calling run's group
(github.run_id is the caller's run id), so no other run of the block,
in either arm, shares it unless one caller run invokes the block more
than once — those invocations share a group and can cancel or queue
each other. A caller workflow named size baseline, in any letter
case, would also share the standalone group — name it anything else.
The block's job commits the records on the default branch. On a push
there with a non-empty push-key, the action first checks that the
checkout's HEAD is github.sha and fails otherwise. It tightens over
that tree; when nothing changes it pushes nothing, so the records
commit's own run ends there. Otherwise it commits only the records file
on top of github.sha, as github-actions[bot] with the message
ci: tighten size-ratchet records, and pushes it as a fast-forward. A
loose record is never a failure, and a record its file grew past stays
as recorded, never raised: growth fails the next pull request checked
against it, the one that causes it unless two merged pull requests grew
the file together.
The run fails only on a malformed records file, a refused push, or a
tree total above its budget (see Tree budgets). When the push is
refused and a fresh read of the remote shows the branch moved past github.sha, the
run pushes nothing and passes with a notice — the newer push's run
measures again; the action never merges or rebases a records file. A
refusal while the branch stands still fails the run and names it.
push-key is an SSH write deploy key, the secret
MASTER_PUSH_DEPLOY_KEY of a <default branch>-push environment whose
deployments are limited to the default branch. It must not be a
repository secret: the key is the DeployKey bypass actor of the
consumer's required-checks ruleset, the one push the ruleset admits
without checks, and a repository secret is readable by any branch's
workflow; the built-in token cannot be that bypass actor. The block's
job-level environment: binds that environment only on a default-branch
push, so its branch policy never refuses a pull-request run, and the same
file serves a main or a master repository. The key exists only in
the action's push step, written to a 0600 file under RUNNER_TEMP and
deleted with it; GitHub's SSH host keys are pinned from GitHub's Meta
endpoint. Pull requests, fork pull requests included, never push.
With an empty push-key the run commits nothing. In the block's own
run (github.workflow is size baseline, the test its concurrency group
uses) nothing else commits the records either: on a default-branch push,
loose records fail the run under require-tight: 'true', and under
'false' each one is a ::warning:: naming push-key as unset, so a
consumer without a key never stops tightening silently. Any other run,
a workflow that uses the action directly included, is a called run; one
that arrives here without a key never fails on a loose record on a
default-branch push, whatever require-tight says, and names each one
in a ::notice:: saying the block's standalone push run commits it.
Under require-tight: 'true' a pull request that shrinks, deletes or
excludes a recorded file — or graduates one by shrinking it below its
ceiling — fails until that entry in the same pull request says what
tighten would write — lowered, or dropped. A ceiling the pull request
raises without moving a count stays a stale notice either way. An
adoption PR that grows or adds no over-ceiling file, and grows no listed
tree folder, needs no records file (see Seeding).
Two pull requests checked against the same base can both merge and leave a record above its file's count — each lowered the record to its own head's count, and the merged tree carries both deletions. The default-branch run tightens every such entry, and a pull request that changes neither the file nor its record passes.
A consumer that today delivers size records from its own push job deletes
exactly that: the size arm of its delivery workflow — the tighten step,
the artifact staging and the commit — and the tests of that delivery.
Records files a delivery also lands for other gates keep their arms, and
the delivery workflow itself stays when they do. Beyond the block, the
adoption adds the <default branch>-push environment with its
MASTER_PUSH_DEPLOY_KEY secret, the deploy key itself, and that key as
the ruleset's DeployKey bypass actor; no extra workflow is added.
| Input | Default | Meaning |
|---|---|---|
ceilings |
'' |
Multiline <type>: <ceiling> lines replacing a type's default. |
overrides |
'' |
Multiline <folder>/: <ceiling> lines; the longest matching repository-relative folder prefix wins. |
exclude |
'' |
Multiline exact paths or <folder>/ prefixes removed from measurement. |
unclassified |
'ignore' |
fail fails a measurable file with no ceiling, no record and no exclusion. |
records |
'.github/size-baseline.json' |
Repository-relative records file. |
member |
'' |
Top-level key of the records file holding the baseline map, instead of baseline. |
mode |
'auto' |
Event dispatch above, or exactly check / tighten to force a mode. |
base-ref |
${{ github.event.pull_request.base.sha }} |
Git revision whose records bind a check. Required for check, unused by tighten and by the default-branch run. |
stale |
'warn' |
warn reports a stale record as a notice; fail fails the run on one. |
require-tight |
'false' |
'true' fails a check whose touched entries differ from what tighten would write, naming each; entries the pull request leaves untouched stay a stale notice. 'false' fails neither, and a default-branch run with no push-key warns on each loose entry. A called default-branch run with no push-key fails on neither value (see Records on the default branch). |
push-key |
'' |
SSH write deploy key that commits the tightened records on a default-branch push (see Records on the default branch). Empty pushes nothing. |
tree-budgets |
'' |
Multiline <folder>/ lines, each budgeting the total line count under that folder (see Tree budgets). Empty budgets no tree. |
Invalid inputs fail the run with exit 2 and name the input and the line: a
malformed line, an unknown type, a folder without a trailing /, a
folder or exclude entry with a leading / or an empty, . or ..
segment (as in ./tests/, tests// or ./src/a.py), a duplicate
folder, or a ceiling that is not a positive integer. So does a folder or
exclude entry with a segment git refuses as an alias of .git: .git
or git~1 in any letter case, at the start of the segment or after a
\ that is not its first character, then any dots and spaces, then the
end of the segment, a : or a \ (as in vendor/.git/, vendor/.git./
or vendor/GIT~1 /). A non-empty
tree-budgets beside member: trees fails the same way. Exit 0
passes, 1 is a violation, 2 is a configuration or environment failure.
Inputs reach the action through environment variables and are never
interpolated into shell programs.
Inputs changed in with: are a workflow edit in the PR diff — they are
reviewed like any workflow change, and the action reads them from the run's
own inputs without comparing them with the base revision's workflow.
Each type has a default ceiling and is chosen by extension. A file with none of these extensions has no type.
| Type | Extensions | Default ceiling |
|---|---|---|
source |
.py, .js, .jsx, .mjs, .cjs, .ts, .tsx, .sh, .bash |
500 |
stylesheet |
.css, .scss |
500 |
sql |
.sql |
500 |
yaml |
.yml, .yaml |
500 |
A typed file's ceiling is the first that applies:
overrides— a<folder>/prefix match, longest prefix wins. An override never gives a ceiling to an untyped file.ceilings— that type's configured ceiling.- the type's built-in default.
Every regular file (mode 100644 or 100755) in git ls-tree -r of the
measured revision that has a ceiling, or has a record, is measured in
lines: the number of \n bytes, plus one when a non-empty file does not
end in \n. Symlinks, submodules and files git reports as binary (a NUL
byte in the first 8000 bytes, git's own rule) are never measured and are
never unclassified; only a tree budget counts a binary file (see Tree
budgets). A file that cannot be read fails the run, naming it.
Check measures the checkout's HEAD; the install block above checks out
the PR head SHA with fetch-depth: 0.
The records file itself is never measured or unclassified: it is the gate's own data, not source.
.github/size-baseline.json holds {"schema_version": 1, "baseline": {"<path>": <lines>}}. With member set, the baseline map is instead the
value of that top-level key, and every other key of the document but
the tree budgets' trees is preserved byte-for-byte on write. All per-file comparisons use only the
baseline map. "No records" means the file is absent or the key is absent; an empty
map is records. Ceilings live only in with:.
- A file with a record may not grow above its record, whether or not it has a ceiling.
- A file without a record may not exceed its ceiling.
- A recorded number is never raised and no entry is ever added by hand: growth is answered by relocating code into a new file, or by shrinking the file.
Check compares the head tree against the baseline read at base-ref,
so a records edit in the head does not loosen the gate. With
require-tight on, or when neither revision has records (see Seeding),
it measures the base tree as well, so the base's counts bind the
comparison. Each failure names the path, its measured lines, and the
record, base count or ceiling it exceeded. A
recorded entry whose file shrank, was deleted, was excluded, or is at or
below its ceiling is stale: stale: warn reports it as a notice;
stale: fail fails the run. require-tight: 'true' also fails
when an entry the pull request changes — its file's count moved between
the base and head trees, or its record moved between the base and head
maps — differs from what tighten would write, naming each entry and what
it should become: a record to lower prints required N against the
recorded value, and a record to drop prints recorded M alone. Entries
the pull request leaves untouched
stay with the stale report: a loose record already on the base never
fails unrelated work. An entry the head adds for an unrecorded
over-ceiling file must be that file's exact head count — the same
exactness the seed fallback demands (see Seeding); any other number, and
any entry added for a file at or below its ceiling, is refused.
Tighten lowers each record to the file's current count. It drops
entries for deleted, excluded and graduated (at or below the ceiling)
files, and keeps an entry whose file has no ceiling, lowered to its count.
It never raises or adds an entry except when seeding. A run with nothing to
change writes nothing and passes. Forced tighten writes only the
checkout; on a default-branch push auto commits what tighten writes
(see Records on the default branch). Force tighten to seed, or to write
the records file for a deliberate commit.
With no records, tighten records every file over its ceiling at its current
count. A check whose base-ref has no records, against a head that has
none either, judges the head by the base tree: a file over its ceiling
there may not grow past its base count, and any other file, at or under
its ceiling at the base or new in the head, may not exceed its ceiling.
A head that carries records over such a base must carry exactly what a
seeding tighten over the head tree writes, and a failure names each
differing entry; any other map fails, so a head edit never loosens the
gate. unclassified: fail fails an untyped, unrecorded file either way,
and require-tight adds nothing for an entry the base does not record.
Once the base has records, only the base's bind. A base whose records
map is empty is the same for additions: an entry the head adds for an
over-ceiling file must be the file's exact head count.
So adopting the action, or a release, is the workflow edit alone: with
no per-file map on the default branch, the first default-branch run
with push-key commits the per-file seed tighten writes, creating the
records file when there is none, with the trees map beside it when
tree-budgets is set (see Tree budgets). Until that map lands, every
pull request is judged by the base tree's counts. A pull request that
grows an over-ceiling file, or adds one, before the base has records
commits the exact seed instead.
Three consequences for an adopting PR:
- A PR that carries a seed regenerates it on every later commit that changes a recorded file's count. The seed binds exactly: a commit that adds ten lines to a seeded file fails the seed-fallback comparison until tighten runs again over the new head.
- The widening limit. After seeding, a change that brings an over-ceiling file under measurement — a lowered ceiling, a removed exclusion, a new type — fails check for that file until it is excluded or shrunk. A release that adds a type is a major version for exactly this reason.
- An adopter that already keeps another size baseline seeds under a new
memberor the default file and deletes the old one in the same PR.
Every file can stay under its ceiling while a folder grows without limit.
Each <folder>/ line in tree-budgets budgets that folder's total: the
sum of line counts, by the measurement rule above, of every regular
file in git ls-tree -r under that repository-relative prefix, typed or
not, minus excluded paths and the records file. A file git reports as
binary counts too, by the same rule, so a NUL byte never hides a
file's lines from its folder's budget. A file under
two listed folders counts toward both. Totals live under the records
file's top-level trees key, {"tests/": 139242}, whatever member
says; member still selects only the per-file map. With tree-budgets
empty, the default, nothing reads, judges or writes trees.
- Tighten seeds a missing budget at the folder's total, lowers one
above it, drops one for a folder no longer listed, and never raises one.
It rewrites only the
treesvalue and the member's value. - Check judges the head against the base's budgets. When the base has
no budget for a folder and the head carries none, the base tree's total
stands in as the budget: the run fails, naming the folder, when the
head's total exceeds it. A head that carries a budget the base lacks
must carry exactly the seed tighten writes, the head's total, and needs
no feature commit; any other value fails, so a head edit never loosens
the gate, and
require-tightadds nothing for that folder. A pull request that grows such a folder carries that seed. Otherwise the run fails, naming the folder, its total and the budget, when the head's total exceeds the head's budget, when the head drops the budget or lowers it below the total, or when the head's budget is above the base's and no commit subject inbase-ref..HEADmatches^feat(\([^)]*\))?!?:(feat:,feat!:,feat(<scope>):orfeat(<scope>)!:) — only a feature change, breaking or not, may raise a budget; any other change trims its own lines under the folder. Reading that history needs a full clone: a shallow or unreadable history fails with exit 2, and is read only when a budget rises. Underrequire-tight: 'true', a folder whose total or budget moved between base and head must record exactly the head's total. - The default-branch run fails when a total exceeds its budget, with
or without
push-key, under eitherrequire-tight. A budget above its total, a missing budget, or a budget for an unlisted folder is loose, exactly like a loose per-file record (see Records on the default branch): a run withpush-keycommits the tightenedtreesmap in one records commit with any tightened per-file map, and with no records file at all commits the document tighten creates, both maps; a called run without the key names it in a notice; the block's own run without the key fails on it underrequire-tight: 'true'and warns under'false'. A records file holding onlytreesis records for the tree budgets; a keyed run adds the per-file seed to it (see Seeding).
With tree-budgets set, the per-file gate and the tree budgets each
report their verdict, and the run fails when either fails.
See CONTRIBUTING.md for the regression suite and the records-update procedure, and SECURITY.md for private vulnerability reporting. Licensed under the MIT License.