- Ship. The task’s pull request goes into the staging branch, not the main branch.
- Land. It is merged there — on your forge (GitHub or GitLab) after review, or by your CI.
- Parked. It waits on the staging branch while it is tested. Fixes go the same way: resume the task, fix, ship again.
- Prepare for prod. When the test passed, you tell your agent “prepare for prod”. Jig opens a second pull request, from the task’s own branch into the main branch, for exactly the commits that were tested.
- Merged into main — by you, or by the forge once CI passes, if your team chose that.
Direct or staging?
Stay on the direct flow unless your team really tests on a staging environment. The staging flow costs something:- Two pull requests per task — one into staging, one into the main branch.
- Task branches must stay clean. Only the main branch and other clean task branches may be merged into a task’s branch. Merging the staging branch into it — “Update branch” on its pull request included — would carry other people’s untested work to production, so Jig refuses it.
- Merge commits, not squash. Jig recognises a task on staging, and a promoted task in the main branch, by git history. A squash or rebase merge hides that (known issues).
.ai/config.yaml, not in
anyone’s personal settings.
Turn it on
-
Create the staging branch on origin, for example
staging, from your main branch. -
Ask your agent to set up Jig (
jig-setup). When origin has a branch namedstageorstaging, it asks which flow the team uses and writes the answer through a task and a pull request, like any other change to the project. For a branch with another name, or by hand, the same keys go in.ai/config.yaml: -
Check it with
jig doctor:A wrong value — the main branch itself as the staging branch, or a name git rejects — fails here, andjig task shiprefuses it before committing anything. - On your forge, allow merge commits, and let whoever resolves conflicts push to the staging branch (see Landing).
jig init and jig doctor only mention the flow when
origin already has a branch named stage or staging, which the staging flow could use.
The settings
See Configuration for every other key.
Switching a project that already has work in progress
- A task branch with an open pull request into the main branch is refused by
jig task ship: in the staging flow its pull request goes into staging. Close that pull request, or retarget it to the staging branch, and ship again. - A branch cut before the switch still carries the old
.ai/config.yaml.jig task shiprefuses it, showing both flows (the git flow here is not the one main has): merge the main branch into the task branch and ship again. - A task of an epic keeps going into its epic branch, as before.
Ship and land
Your agent ships the task as usual (Let your agent ship). In the staging flow the pull request goes into the staging branch:agent.git, your own setting for what the agent may do with git, or on
agent.git_staging when you set it: the level for a task whose pull request goes into the staging
branch. At merge the ship also lands the task; below it, the ship stops at the pull request, and
you (or your agent, when you ask) land it later with jig task land <id>.
agent.git_staging lets the agent land on the staging branch without merging anything into your
main branch. With agent.git: pr and agent.git_staging: merge, your agent lands its own tasks on
the staging branch once CI passed and the review rule allows, while Jig upgrades, specifications,
epics, releases and promotion still stop at a pull request for you. Not set, agent.git answers
everywhere, as before. A task of an epic and a task that changes the git flow itself go into their
own base, and agent.git decides those. These settings limit what Jig does for your agent: an agent
that bypasses Jig (gh pr merge) is held only by the “Jig first” rules in your project’s
instructions and by the forge’s branch protection.
agent.git and agent.git_staging limit only the agent. When you land the pull request yourself — a button in your
dashboard, or jig task land <id> --by human in a terminal — Jig does not read it, whatever it is
set to. You press it on what you saw, so Jig looks at the checks once and never waits for them; a
conflict is refused (your agent lands those with jig task land <id>); and the forge’s branch
protection always holds: Jig never overrides it. --without-review lands a pull request nobody
approved, under ask, and says so on the pull request. The same --by human is on
jig task promote <id> (“prepare for prod”), jig task request-review <id> --reviewer <login> and,
for a pull request that goes straight into your main branch, jig task merge-pr <id>.
Landing
- Review first, as
git.staging_reviewsays. Withask, a pull request nobody approved stops (exit 3) and your agent asks you: land without review —jig task land <id> --without-review, which also says so on the pull request — or wait. An autopilot run always waits. A pull request is approved only once every reviewer it asks has answered: one approval while another requested reviewer has not looked readsnot approved (waiting for bob), and changes requested by anyone win over everything. On GitHub a reviewer who only commented counts as answered, as GitHub itself counts it; on GitLab a reviewer counts once they approved, and approval rules that want more approvals wait too. - Who reviews is chosen for each task, never kept in a setting. Before the ship your agent asks
you one question with the three or four people who reviewed most of the recent pull requests into
staging (
jig pr reviewerslists them; with no such history, everyone the repository may ask), and the ship requests them on the pull request it opens:jig task ship <id> --reviewer alice --reviewer "Sikora". A name resolves to one login among the people the repository may ask, or is refused naming the matches; teams are refused — one member’s review would clear a team — and you, the pull request’s author, are left out. An autopilot run asks nothing and requests nobody. - Merged on the forge when it merges cleanly: with a merge commit, and only on green CI. A red
check or a refusal from the forge leaves it open:
not landed: <why>. - Merged directly only when it conflicts. Jig merges the task into a temporary copy of the
staging branch beside your project (
<project>.worktrees/.land-<id>), never in your checkout, and stops (exit 5) with the files in conflict. The agent resolves them there, runs the tests that matter, and continues withjig task land <id> --resolved --note-file <file>, the note saying how each conflict was resolved. Jig commits the merge with that note, pushes the staging branch without ever forcing it, and comments on the pull request; when someone pushed to staging in the meantime it fetches again, merges again with the same resolution and pushes again.jig task land <id> --abortgives it up. - A push the staging branch refuses — a protected branch, a hook — stops (exit 3) and keeps the merge in that temporary copy, for you to push with your own rights or land on the forge.
Landing by your CI
Withgit.staging_land: external your pipeline merges task branches into staging. jig task ship
pushes the branch and stops there: stopped at push: git.staging_land is external…. It opens no
pull request and merges nothing. Once your CI has merged the branch (with a merge commit), the
task shows as parked for signal in jig status after a git fetch. How your pipeline picks the branches
to merge is yours; Jig names task branches by git.branch_template.
Parked: tested on staging
A landed task is parked: finished for now, waiting for the test.jig status shows it, and
housekeeping keeps it instead of archiving it:
review— its pull request into staging still waits for a review.landingis added once the pull request is approved (orgit.staging_reviewisnone) and you land it yourself: while it waits for a reviewer, has changes requested, or nobody has looked,jig statussays so and a board built onjig task list --jsonoffers no landing. Jig reads the review from what the lastjig housekeepingheard from the forge, so run it to refresh.signal— it is on staging, waiting for someone to say “prepare for prod”.staging=behind— a task you took back for a fix: its branch has commits the staging branch does not have yet.
jig queue next does not offer it, so you and your
agent go on with other work while it is tested. The full description of these lines is in
Manual control.
A task that failed its test is fixed the usual way: jig task resume <id> (or just ask your agent to
continue it), fix, verify, and ship again. The fix lands on staging like the first change.
Prepare for prod
When QA says the task is ready, tell your agent “prepare for prod”. It runsjig task promote <id>, which opens the pull request from the task’s branch into the main branch:
--commit, the tested commit is the staging branch’s tip on
origin as it is now: whatever is on staging when you say “prepare for prod” is taken as tested. When
the test ran on an earlier commit, name it: jig task promote <id> --commit <sha>.
It refuses, and sends nothing, when:
- the task is not on the staging branch (
not-on-staging); - the task’s branch has commits the tested commit does not have — a fix made after the test
(
behind-staging): ship the fix, test it, then prepare for prod again; - the staging branch was merged into the task’s branch (
carries-staging); - the clone is shallow (
shallow-clone); - the task runs on autopilot: autopilot never promotes, only a person says “prepare for prod”.
jig task promote needs agent.git at pr or above; below that it stops
(exit 3) and leaves the pull request to you. Exit 0 means the pull request is open, or the task is in
the main branch already; 1 a refusal; 3 that a person is needed.
After the promotion merges into the main branch, the task is finished like any other: housekeeping
counts it under needs consolidation, and your agent closes it. Landing on staging does not close a
task.
Prepare for prod from CI
A pipeline can run the same command, with the staging commit it tested:CI variable set, and no workspace for the task, as on any real runner — it
needs no agent.git, only:
- the full history:
fetch-depth: 0on GitHub Actions,GIT_DEPTH: 0on GitLab; - a forge token for
ghorglab. On GitHub Actions use a personal access token or a GitHub App token, notGITHUB_TOKEN: a pull request opened withGITHUB_TOKENstarts no workflow, so its required checks never report, and a merge it makes starts no workflow on the main branch, so nothing deploys.
jig task promote --commit <sha> <id> <id>… promotes each one named;
jig task promote --commit <sha> --all promotes every task branch on origin whose tip the tested
commit contains and the main branch does not have yet. --all is for a team whose green CI is the
test, and always needs --commit, so a build that merely ran never sends the whole staging branch
to production. Each task is judged on its own against the same commit, and gets its own line — here
a run with two task ids named:
--all, a task given a fix after the test is skipped and named
(skipped <id>) without failing the run; named explicitly, as T-14 above, it is refused.
--title and --body-file are for one task only.
Keep in mind with --all:
- it reads “not yet in the main branch” from git history alone, so merge promotions with a merge commit, or have the forge delete the task branch on merge;
- do not run it while an epic branch is on the staging branch: a runner cannot tell the epic’s tasks from the others;
- a task reverted on the staging branch still reads as tested: name the tasks instead.
Let the forge merge promotions
Withgit.promote_merge: auto a promotion merges itself: jig task promote switches on your
forge’s auto-merge (a merge commit, at the promoted commit), and the forge merges once the main
branch’s required checks pass. In your own checkout that needs agent.git: merge; on a CI runner
the team’s setting alone decides.
It is switched on only where CI really gates the merge — otherwise the forge would merge at once:
- GitHub: the repository allows auto-merge and merge commits, and the main branch requires a status check (a ruleset or branch protection).
- GitLab: the project requires a successful pipeline to merge, merges with a merge commit, and does not count a skipped pipeline as a success.
Watch the staging branch
jig status reports how staging and the main branch drift apart:
- tasks on staging that nobody promoted for longer than
git.staging_stale_after; - tasks whose promotion conflicts with the main branch;
- your own commits on staging that belong to no task — committed there by hand, a branch merged without a task, or a squash — until you mark them as known.
jig staging ack --dry-run,
bring to the main branch through a task whatever it still needs, and run jig staging ack: it marks
the rest as known in your clone, and from then on jig status names only commits of yours that are
new. A mark follows the change, not the commit, so a rebase or cherry-pick on staging does not bring
it back.
The same appears in the status page and in jig status --json
(Reading Jig as data); the lines are described in
Manual control.
Limits
The staging flow is new in 0.45.0. Its tests run against stand-in remotes; it has not yet been run on a real team’s project, nor on GitLab. What is known not to work yet — squash merges, epics on staging,--all after a revert — is on Known issues.