Git and GitHub Workflow#
How a change travels from a local branch to a merged pull request on main.
Branch Strategy#
Osprey follows GitHub Flow: a single long-lived branch (main) with
short-lived topic branches that PR back into it. Releases are CalVer tags
(vYYYY.M.P) on main — no separate release branch.
What this means for contributors:
Branch your work off
main, and open your PR againstmain.mainis always the integration target. CI gates every PR; protected status checks must pass before merge.Releases are cut by maintainers tagging a commit on
main; the PyPI publish workflow runs onv*.*.*tags.The
osprey-connectorsworkspace package has its own CalVer stream, on its ownosprey-connectors-vYYYY.M.Ptags (bN/rcNfor pre-releases), cut when the package changes. Each release stays backward-compatible with every supported framework release, enforced in CI by theconnectors-compatandframework-at-connectors-floorlanes, so the framework declares only a floor on it, never a pin. (Theosprey-connectors-v0.1.0tag predates the scheme and is retired; the describe glob skips it.) A fork or mirror must sync theosprey-connectors-v*tags as well as thev*ones: without them the package builds as0.0.postNandosprey up --devrefuses it. Connectors releases are stable by default: a beta framework installs with pre-releases admitted and would absorb a connectors beta. A connectors tag runs its own publish workflow,release-connectors.yml, and nothing else: the framework’sv*.*.*release never builds the package, and resolves itsosprey-connectors>=floor from PyPI, so a floor bump lands only after the connectors release it names is published.The
osprey-optimizerworkspace package versions with the framework’s calendar stream and releases from the samev*.*.*tag: one tag publishes the framework and optimizer wheels, always carrying the same number.A change to what ships in the connectors wheel carries its changelog fragment in
packages/osprey-connectors/changelog.d/, which feeds that package’s ownCHANGELOG.md; every other shipped change carries one in the rootchangelog.d/. The README in each of those directories says which files need a fragment, and the changelog check names them in every verdict.Hotfixes follow the same path: branch from the tag (or
main), PR back, tag again asvYYYY.M.P+1. No special hotfix branches.Documentation publishes on the same tags: the site root is always the newest release; every push to
mainrebuilds/latest/, shown with a development banner.
Branch Naming#
feature/description– New featuresfix/description– Bug fixesdocs/description– Documentationrefactor/description– Code refactoringtest/description– Test improvements
Making Changes#
1. Create a branch:
git checkout -b feature/your-feature-name
2. Make changes – follow the code standards on Development Setup, add tests, update docs.
3. Test locally with the check command, scripts/check.py, which runs
the merge gate from the checks every owner declares:
# The quick tier -- before every commit (--fix lets ruff and prettier rewrite
# files first)
uv run python scripts/check.py quick
# The full tier -- before pushing or opening a PR
uv run python scripts/check.py full
# The quick tier scoped to your diff (name your PR target; add --worktree
# to judge uncommitted changes too)
uv run python scripts/check.py quick --changed origin/main
uv run python scripts/check.py list prints what each tier runs. The scoped
run also names the CI lanes your diff touches. --base BASE arms the checks
that judge a range without scoping the tier, so full --base origin/main
judges the whole tree and the range in one verdict. Before any check runs, the
command puts the tree’s pins in place: the pinned Claude Code first on PATH
for the test sweep, npm ci when node_modules differs from
package-lock.json, and uv sync when an editable install predates the
tree’s tags. When it cannot, it refuses and names what to install. A machine
that cannot judge (too little free disk, an install the sync left stale, Docker
storage that fails) prints check: environment: <probe>: <fact>, runs
nothing and exits 3.
A check is declared by the code that owns it, in a repo_checks.py module
beside that code: scripts/repo_checks.py holds the framework’s and the
repository-wide checks, and a package that brings checks of its own, such as
packages/osprey-connectors/, carries its own module. scripts/check.py
collects every such module in the tree; it holds no check itself. Each record in
a module’s CHECKS carries everything the command does with the check – its
command, scope, tiers, needs, bound and hooks – so adding a check is one record
in its owner’s module and a CI step that calls scripts/check.py run ID.
JavaScript (*.js and *.mjs) is formatted by Prettier, exact-pinned in
package.json and configured by .prettierrc.json: npm run format
rewrites the tree, and the prettier check (npm run format:check) fails
any file it would rewrite. Markdown, YAML, JSON, CSS and HTML are not formatted.
Type a value at its declaration, as a typed local or a typed constant, never
with a cast mid-expression: the formatter moves the parentheses such a cast
depends on, and the cast then types a different expression.
4. Commit changes using conventional commit format:
git add .
git commit -m "feat(scope): short description
- Detail about what changed
- Another detail"
Commit Message Format#
feat:– New featuresfix:– Bug fixesdocs:– Documentationrefactor:– Code refactoringtest:– Testschore:– Dependencies, build
Every pull request that touches a directory the changelog gate covers needs a
changelog fragment: a small file in changelog.d/ named <name>.<type>.md
(use the issue number as the name when there is one).
uv run python scripts/changelog_fragments.py check --base origin/main names the
directories the gate covers in every verdict. The lint CI job checks for a fragment,
and uv run python scripts/check.py quick --changed origin/main checks the same thing locally. Fragments
are folded into CHANGELOG.md when a release is cut — never add entries to
CHANGELOG.md by hand. See changelog.d/README.md for the type list.
Pull Request Process#
Push your branch:
git push origin feature/your-feature-nameOpen a PR on GitHub with a description, related issues, and testing performed.
PR requirements: pass all required CI checks, include a changelog fragment in
changelog.d/when the changelog gate asks for one, and add appropriate tests. Internal-mode contributors with push access self-merge after CI is green (branch protection requires zero approving reviews); fork-mode contributions wait for a maintainer to merge.During review: respond to feedback promptly, make requested changes, ask questions if unclear.
Branch Protection on main#
Direct pushes to main are rejected. All changes land via PR. GitHub branch
protection on main enforces:
The required status checks must pass:
pre-commit.ci - prandAll CI Checks Passed(the aggregate job every CI lane feeds). Admins cannot bypass them.Force-pushes and branch deletion on
mainare denied.
Linear history is not enforced: a PR may land as a merge commit or a rebase,
and both appear in main’s history.
However a branch catches up with main, its conflicts are resolved by
principle 8 of the design principles:
where two lines of work meet, design from the end product.
If a required check turns out to be wrong, fix it forward — there is no escape hatch.
Model-Spending Lanes: full-ci on a PR, On Demand on main#
The CI lanes the LANES table in scripts/repo_checks.py marks why="models"
(the workflow wiring test holds the set against the workflow) drive real agent
sessions against a live model endpoint. Together they cost about $15 per run (measured on the
gateway ledger, week of 2026-09-01: ~150 runs a week, ~$2,300, on pace for $10k
a month, 95% of the group’s model spend) — and they used to run on every push of
every pull request, which at this repository’s pace was the group’s whole model
bill.
They now run on exactly two events:
A pull request carrying the ``full-ci`` label. Opt in per PR, for a change that touches what these lanes cover:
gh pr edit <number> --add-label full-ci
Applying the label starts a fresh run of the PR’s workflow (the workflow subscribes to the
labeledactivity); the superseded run is cancelled. TheAll CI Checks Passedrun summary of every unlabeled PR names the lanes that skipped and prints this command.The ``revalidate_secret_lanes`` dispatch against any ref: the maintainer path described under Dependency Update Pull Requests below, and the way the lanes run against
mainat all:gh workflow run ci.yml --ref main -f revalidate_secret_lanes=true
A release-notes pull request always carries full-ci: these lanes are the
only proof the agentic paths work on the tree about to be tagged.
On main, .github/workflows/main-full-ci.yml starts that dispatch once a
day, and only when main has moved since the last revalidation run, so a quiet
day spends no model tokens. A red revalidation run opens or updates the one
“Full CI red on main” issue, and the next green run closes it, so a red reaches
a person. If you consume main directly, pin a sha a full run was green on
rather than raw head. This prints the newest such sha, for the whole run or for
one lane; it reads the runs through gh, so sign in to the GitHub CLI first:
python3 scripts/ci/full_ci_on_main.py last-green
python3 scripts/ci/full_ci_on_main.py last-green scan-agentic-e2e
Everything else on a PR is unchanged: the unit, lint, docs and package lanes and every secret-free e2e lane (build-and-boot, deploy, bluesky, auth, podman) still run on every push. Those cost runner minutes, not tokens, and the deploy lanes are the per-PR proof that a render builds and starts.
Path filtering was measured and rejected as the mechanism for the
model-spending lanes: over the 161 PRs
merged in the two weeks before this landed, 86–91 % touched something under
src/ that the broad lanes cover, so a filter map would have saved about a
fifth and needed maintaining. The label is the whole mechanism; the stop-loss
behind it is a daily budget on the CI gateway key.
Every PR and main push keeps one live run per ref: a new push cancels the
run for the previous head. Before that grouping, superseded runs kept running
and queued ahead of the live one on a saturated concurrent-job allowance:
measured over 71 PR runs, 35 % were superseded runs still holding 31 % of all
CI wall-clock.
Once a cheap, deterministic lane fails (lint, the docs build, the package
build, the frontend JS checks, the plugin smoke), the run cannot pass, so a
pull request’s run cancels its remaining lanes, All CI Checks Passed
included. Push a fix or re-run the workflow to merge.
Measured CI Figures#
Lane |
What |
Figure |
Where measured |
Date |
|---|---|---|---|---|
|
tests/{registry,connectors,mcp_server,cli} on 3.12: bare / ctrace / sysmon |
150 s / 283 s / 130 s |
developer host |
2026-08-21 |
|
CI cells: 3.12 (sysmon) / 3.11 (ctrace) |
14.6 min / 36.1 min |
GHA |
2026-08-21 |
|
rest-a / rest-b / rest-c share of non-cli test time |
32–35 / 33–37 / 31–32 % |
GHA per-test event logs |
2026-11-06 |
|
cli-a share of tests/cli test time |
51 % |
GHA per-test event logs |
2026-11-06 |
|
whole cycle, cold / warm |
~33 min / ~7.5 min |
Apple Silicon host |
2026-08-11 |
|
whole module, warm layer cache |
6 min 55 s |
developer host |
2026-08-27 |
single-build auth lanes |
one cold image build |
7–11 min |
runner |
2026-08-26 |
|
whole module: project image built / warm / warm with history cases |
~5 min / ~1 min / 114 s |
developer host |
2026-10-11 |
|
VA image cold / bench IOC image / three modules (54 tests) / total |
226 s / 1 s / 214 s / 7.4 min |
Apple Silicon host, amd64 emulated |
2026-08-27 |
|
run step |
3.6 min |
Apple Silicon host, amd64 emulated |
2026-08-27 |
|
VA image cold / bench IOC image / module (10 tests) / total |
226 s / 1 s / 281 s / ~8.5 min |
Apple Silicon host, amd64 emulated |
2026-08-24 |
Dependency Update Pull Requests#
Dependabot opens pull requests for dependency bumps, subject to a seven-day cooldown: a release is not proposed until it has been public for a week, so that a hijacked or malicious version has time to be found and yanked before it reaches this repository. Security updates are exempt, by design — a fix for a known vulnerability should not wait.
These pull requests run with a deliberate gap in coverage. GitHub treats a
Dependabot-triggered run as if it came from a fork: it receives only the
Dependabot secret store, never the repository’s Actions secrets. The lanes that
need a live model endpoint therefore skip rather than run — the agentic
flows, the E2E suite, the dispatch stacks, and the two chat bridges. The run
summary of the All CI Checks Passed job names them explicitly, so a green
check on a dependency PR is never mistaken for full coverage.
To close that gap before merging, review the diff and then revalidate the branch yourself. Because you trigger it, that run gets the normal secrets:
gh workflow run ci.yml --ref <dependabot-branch> -f revalidate_secret_lanes=true
Find the branch name with gh pr view <number> --json headRefName. Watch the
resulting run to completion before merging.
The reason this is a manual step rather than an automatic one is worth stating: mirroring the model API key into the Dependabot secret store would make these lanes pass unattended, but it would also hand a live credential to a newly-published third-party package at install time — the precise supply-chain exposure the cooldown exists to reduce. The human read of the diff is the point, not an inconvenience around it.
OSPREY Agent Workflow Skill#
If you use the OSPREY agent (e.g., via Claude Code),
the /osprey:contribute skill gives guided help following this workflow. It
walks you through branching, commits, push, PR, and CI iteration,
auto-detecting whether you have push access to als-apg/osprey or are
contributing from a fork. It ships in the osprey plugin alongside nine
others; how to install it, and which skill fits which step of the journey, is
on Agent Skills.