Internal notes for maintaining the Supabase CLI contribution workflow. See
CONTRIBUTING.md for the contributor-facing version.
External pull requests are only accepted when they link to an open GitHub issue
that carries the open-for-contribution label. This is enforced by the
Contribution Gate workflow, whose decision logic
lives in scripts/contribution-gate.ts.
The gate sweeps every open PR every 15 minutes, at minutes 7, 22, 37, and 52 of each hour (UTC), and can also run manually. GitHub can delay or drop scheduled runs, so enforcement has no fixed response time. Opening, reopening, or editing a PR does not trigger an immediate run.
Both scheduled and manual sweeps run only from the default branch. They execute repository code, never PR code, and share a concurrency group to prevent overlap. The schedule starts once this workflow reaches the default branch.
During a sweep, a pull request is closed with an explanatory comment when the author is external and any of these is true:
- no issue is linked (via a closing keyword such as
Closes #123, or the PR's Development sidebar), or - the linked issue is closed, or
- the linked issue is missing the
open-for-contributionlabel.
Sweeps also catch issue closures and label removals without a PR edit. Reopening a PR does not bypass the policy: link a qualifying issue before reopening, or the next sweep will comment and close it again.
Authors whose author_association is OWNER, MEMBER, or COLLABORATOR, and bot
accounts, are exempt — Supabase maintainers can keep working from Linear tickets that
aren't public on GitHub.
Use Actions → Contribution Gate → Run workflow from the default branch to sweep
all open PRs on demand, for example after bulk-applying open-for-contribution labels.
Runs from other branches are skipped. Set the dry_run
input to true first to log each PR's decision in the run output without commenting on or
closing anything; run again with dry_run unchecked to apply the decisions.
During triage:
- Categorize the issue with one of
✨ Feature,🐛 Bug, or📘 Docs. Issues opened via the templates start with their category label already applied. - When the issue is ready to be worked on, add the
open-for-contributionlabel.
The open-for-contribution label must exist as a repository label for this workflow to
function; create it once from Issues → Labels if it is missing.
Applying open-for-contribution is currently a manual step — do it on the GitHub
issue directly (from the GitHub UI, or from the Linear-linked issue).
Ready (non-draft) PRs targeting develop already get the default suite: Test
(check / unit+integration / e2e) and PR-title lint.
Stacked PRs (base is another PR branch) and drafts do not get that suite
unless they carry the run-ci label. run-ci.yml
then calls Test as a reusable workflow, including while the PR is still a draft.
- Add
run-cito start (or resume) the suite; remove it to cancel in-progressrun-ciruns via that workflow's concurrency group. - Other labels do not start or cancel Test. PR-title lint may retrigger because that check is cheap.
- After a stacked PR is retargeted onto
develop, push or reopen so the native required checks (Check code quality, etc.) populate. The opt-in suite uses different check names (Test / Check code quality). - This is independent of
run-preview-packagesandrun-live-e2e-ci.
The run-ci label must exist as a repository label; create it from
Issues → Labels if it is missing.
CLI preview packages are large, so they are not published on every PR.
Add the run-preview-packages label to publish via
publish-preview-cli-packages.yml
(any base branch, including drafts). While the label stays on, each subsequent
push re-publishes; remove it to cancel in-progress runs.
The workflow posts (or updates) a PR comment with an npx install command for
the preview. This is independent of run-ci and run-live-e2e-ci.
The run-preview-packages label must exist as a repository label; create it
from Issues → Labels if it is missing.
flaky-check.yml runs one commit on many fresh
runners with retries off. A test that passes in some runs and fails in others is
reported as flaky; one that fails in every run is reported separately.
| Trigger | Commit | Suites |
|---|---|---|
| Nightly, 03:17 UTC | develop |
unit, integration ×10 |
| Weekly, Sunday 03:47 UTC | develop |
CLI e2e, stack e2e ×3 |
run-flaky-check label |
PR merge commit | unit, integration ×10, plus focused |
| Manual dispatch | any ref | chosen suites, runs, repeats, and file filter |
focused runs the tests affected by the PR (vitest --changed against the merge
base) five times per job, each in a fresh Vitest process, to show a flaky-test fix
holds; a changed package.json or Vitest config selects every test. Dispatch with
suites=focused and a filter to target specific files.
The label is removed when the run starts, so re-add it to run again (by hand on
fork PRs, which also get no comment). The report goes to the job summary, the
flaky-check-report artifact, and one PR comment, and fails the run when any test
failed or any run produced no results.
The run-flaky-check label must exist as a repository label; create it from
Issues → Labels if it is missing.
Live E2E exercises managed staging after every push
to develop, daily at 06:23 UTC, and on manual dispatch. The nightly run also
dispatches main and next (when it exists), so each branch has its own runs. New develop pushes
replace only a queued push run; nightly and manual runs execute independently.
Nightly runs do not depend on a new beta version: they also detect staging
changes between CLI releases.
Stable and maintenance publishing requires a passing live suite for the exact
release commit. The release workflow reuses a verified successful staging run
for that commit when available; otherwise it runs the suite before publishing.
Normal promotion fast-forwards that commit from develop to main, so stable
reuses the develop run. The gate queries runs of live-e2e.yml for the
branch passed in its branch input (develop by default, the v<N>.x ref for
maintenance releases); renaming the workflow requires updating that selector. Actions API lookup errors and live-test
failures block publication. This also applies to
manual stable releases. Beta publication keeps its existing build and smoke-test
gates.
Live-test failures and recoveries are sent to the channel configured by
SLACK_RELEASE_WEBHOOK, with commit and workflow links. Routine successful runs
stay quiet. GitHub Actions logs contain the test failures; notification delivery
does not determine whether the suite passed.
PR live coverage remains opt-in through run-live-e2e-ci. That label dispatches
the PR commit to the separate Supabox harness, which also has its own nightly
schedule against pinned submodules. A Supabox result does not replace the
managed-staging gate for stable publication.
The gate and notifier identify the reusable suite by the Live e2e job name (or
the exact / Live e2e suffix). The gate also checks the Run live e2e step
name. Keep these names aligned with their consumers. Push, scheduled, manual, and stable-gate runs
use separate concurrency groups because they own independent temporary project
sets; this is intentional and does not imply a global concurrency quota.
Notification history inspects at most 25 recent runs of the same workflow and
branch. It suppresses repeated outcomes and results superseded by a newer run
or attempt. Recovery requires a known prior failure. History lookup errors
produce warnings; a confirmed current failure can still be reported if its
prior outcome is unknown. Release failures use the existing release notification
to avoid a second failure alert from the live notifier.
Full procedures live in the release process runbook; the decision is ADR 0028.
Resolving a sync PR. When Sync branches cannot merge cleanly it opens
sync/<source>-into-<target> (for example sync/develop-into-next); CODEOWNERS
requests the CLI team, and for main-into-develop the release Slack channel is
also told. Further syncs for that pair skip while it is open. For
develop-into-next, Claude resolves the merge on the branch and repairs CI
failures and AI review findings; check its comments, answer any decision it
lists, and approve
(runbook).
Otherwise merge the target into the sync branch, resolve, and push; then
approve the PR. Approval fast-forwards the
target and deletes the branch. Never use the merge button. A moved source does
not block landing; the next sync run brings its newer commits in. If the target
moved, the bot merges the latest target into the approved head and lands it
directly if the merge is clean, as for a clean sync (the merge commit is
untested); only a new conflict, or a target that keeps moving, sends the PR
back for a new approval. Only two sync pairs
exist (sync/main-into-develop into develop, sync/develop-into-next into
next), and only the release bot's PRs from those branches qualify; approving
a hand-made PR from one of them is refused with a comment (close it and run
gh workflow run sync-branches.yml -f pair=<pair>). One
maintainer may both resolve and approve a sync PR: that is an accepted
decision, since resolvers are trusted maintainers and the resolution is not
independently reviewed.
Approving a fast-forward. The approver needs write access, and the approved
commit must still be the PR head with the four required checks green.
Fast-forward PRs are the deploy PR (develop → main), the major cut
(next → develop), and the two sync PRs.
Dispatch guards. release.yml refuses channel=next off next,
channel=next while next has no commits beyond develop,
channel=maintenance off v<N>.x, beta/stable on next or v<N>.x, a
non-dry-run stable outside main, and a version that is not
X.Y.Z[-prerelease].
release-major label. The deploy fast-forward refuses a major version bump
unless the deploy PR carries release-major. Add it only when shipping a major
on purpose.
Cutting a major. Pause the develop merge queue, make sure next contains
develop (no open sync/develop-into-next PR), open a PR next → develop
and approve it, then resume the queue. See
Cutting a major.
Maintenance releases. After a fix merges into v<N>.x, dry-run first, then
publish; leave version empty:
gh workflow run release.yml --ref v2.x -f channel=maintenance -f dry_run=true
gh workflow run release.yml --ref v2.x -f channel=maintenance -f dry_run=falseOnly security fixes and fixes for fundamentally broken behaviour go into
v<N>.x, through hotfix/* or backport/* PRs. Release-infrastructure changes
must be cherry-picked to every active v*.x (see
Release infra and maintenance lines).
Hotfixes. A stable fix that cannot wait for the weekly deploy is a
hotfix/* PR into main titled fix, perf, or revert. Its checks,
including the dry-run release rehearsal, run on every push. After it publishes,
Sync branches merges main into develop; a conflict is announced in Slack.
There is no rollback: ship a revert: hotfix instead. See
Hotfix release flow.
Manual setup (rulesets and labels).
- Create the
nextbranch fromdevelop, and therelease-majorlabel. - Add
Require fast-forward(frombranch-policy.yml, which runs onpull_request_target) as a required check ondevelopandnext.nextalso needs the merge queue, the four checks required ondevelop(Check code quality,Run unit and integration tests,Run end-to-end tests,Lint Pull Request), and release App bypass. - Add a
v*.xruleset with release App bypass andCheck maintenance sourceas a required check. - Confirm the npm trusted publisher for
supabasestill points atrelease.yml.
We considered auto-applying open-for-contribution when a Linear issue moves out of
Triage/Backlog (e.g. to Todo). Linear's native GitHub automations are one-directional
(GitHub events update Linear status) and cannot push a GitHub label, so this would need an
external bridge (a scheduled job polling the Linear API, a Zapier/Make zap, or a Linear
webhook → relay). It is out of scope for now and tracked separately; until then, apply
the label manually as above.