Turn it on
Send this in your AI chat:For developers: configure Git permissions by hand
For developers: configure Git permissions by hand
-
Create
.ai/config.local.yamlin your project if it does not exist, and add one line:The file is yours: Git ignores it, andjig initadds it to.gitignoreif an older project does not ignore it yet. -
For
pr, the agent opens the pull request with GitHub’sghor GitLab’sglab. Install the one for your host and sign in once:Without a signed-in tool the agent still commits and pushes, then tells you the pull request is yours to open. -
Check it took effect:
agent.git in the committed .ai/config.yaml does nothing: that file is shared with
everyone, and a shared value would switch every contributor’s agent on. jig status and
jig doctor warn when they find it there.Choose how far it goes
Think about what you want to happen when a change is ready. These are three useful starting points; the agent can also help you choose a step in between.Leave the result for me to check
Prepare everything for review
Add checked changes automatically
For developers: all five Git permission levels
For developers: all five Git permission levels
pr, merging is your decision. The same levels apply to a specification’s epic
(Specs and epics).If you choose automatic completion
This option needs automatic checks already set up for your project. The agent waits for them; if a check fails, no checks ran, or a required approval is missing, the change stays waiting. What you do then: read the agent’s explanation. Ask it to fix a failure or explain whose approval is needed. It cannot simply ignore the project’s rules to finish.For developers: automatic merging, CI, and branch protection
For developers: automatic merging, CI, and branch protection
agent.git: merge, jig task ship opens the pull request, waits for its checks and merges it —
only when at least one check ran and every check passed (it waits up to agent.ci_timeout minutes,
30 by default, set in the same file), the review left nothing serious open, the pull request is not
a draft and it is exactly the commit that was shipped. It merges the way your repository allows: a
merge commit, else squash, else rebase.agent.git limits only what the agent does on its own. When you merge or land a pull request
yourself, with jig task merge-pr <id> --by human or jig task land <id> --by human (or the same
button in a dashboard), Jig does not read it: at none you can still merge from the card. Branch
protection holds for you too.It never uses an administrator’s override and never asks the host to “merge when ready” later. When
your repository’s branch protection refuses — a required review, for example — the pull request
stays open and ship says why:ship switches
you back to the main branch, brings it up to date and deletes the task’s branch, here and on the
remote. Shipped from the task’s own worktree, the branch stays until housekeeping removes the
worktree after the task is closed, and deletes the branch then (on the remote too, at push or
higher). Only Jig’s own branches are ever
deleted, with git branch -d — Git itself refuses one holding a commit that is nowhere else. When
another tool (an IDE’s background fetch --prune) already removed the branch’s remote copy and Git
refuses, the branch still goes if its last commit is exactly the one the
hosting site merged, or an earlier one; a branch with anything newer stays. On the remote a branch
is deleted only while it is still at the commit that was merged. Set
git.delete_merged_branches: false in .ai/config.local.yaml to keep every branch. Together with autopilot.unattended: true it is how a
run finishes without you (Autopilot: without stops).What happens at the end of a task
The agent checks its work, records anything future sessions need to know, and takes the final steps you allowed. Ask it to make the result clear:For developers: what task shipping records and runs
For developers: what task shipping records and runs
- records what the project should remember from the task — or that there is nothing;
- stages the task’s own changes, and only those — if other work sits in the same folder, it stays out of the commit;
- writes the commit message: the first line becomes the pull request’s title, the rest its description — what the task was for and how it was checked;
-
runs
jig task ship, which does the Git part as far as your level allows and reports each step:At a lower level it says where it stopped, for examplestopped at push: the pull request is the human's.
git.flow: staging), a task cut from the main branch opens its
pull request into the staging branch instead, and none into the main branch. At merge the ship
also lands it there; below merge it stops at the pull request and you land it later with
jig task land <id>. When the task has been tested, “prepare for prod” (jig task promote <id>)
opens a second pull request, from the task’s branch into the main branch. A task of an epic still
goes into its epic. Before shipping onto staging your agent asks you who should review, offering the
people who reviewed recent pull requests there, and jig task ship <id> --reviewer <login or name>
requests them on the pull request it opens; it lands only once every one of them has answered. The
whole flow — setup, review, landing, conflicts, promoting from CI, auto-merge — is on
Test on staging first.A different choice for autopilot
You can trust a task the agent runs on autopilot further than the work you follow step by step, or less far. A common choice: the tasks you go through with the agent, answering its questions, end on a review page you merge yourself; the tasks you hand to autopilot are added to the project on their own once the automatic checks pass. Say so:For developers: autopilot.git
For developers: autopilot.git
autopilot.git takes the same five levels as agent.git and is read the same way — only from
.ai/config.local.yaml. It decides how far jig task ship goes for a task whose autopilot run is
going (jig task autopilot <id> start until end, a phase run’s
tasks included; a run stopped to ask you is yours again, and goes by agent.git), and how far jig spec ship goes when autopilot.unattended is true. Everything
else — a task shipped outside a run, jig upgrade — goes by agent.git. Not set, it is agent.git.agent.git: merge, autopilot.git: pr) a run stops at the pull
request. release.merge: human still keeps every release’s merge yours: any pull request whose change
raises the version.You can see which one decides: jig status prints autopilot.git: merge (from autopilot.git) or
(from agent.git), jig task route <id> and jig task autopilot <id> start print
autopilot git: <level> (<key>), and jig task ship names the key it went by:
task ship: git level merge (autopilot.git).agent.git_staging is a level of its own for
a task whose pull request goes into the staging branch; see
Ship and land. Not set, agent.git answers there as everywhere.
When a project takes several tasks
You may want to collect several completed parts before releasing the whole feature. Tell the agent what should be usable first and when you want other people to receive it. It will help plan that work and explain the decisions that need you. Your choice above also governs how far the agent can take that larger piece of work. You do not need to learn the branch commands to discuss the release.For developers: specifications, epic branches, and releases
For developers: specifications, epic branches, and releases
jig spec ship <id>, which works out which of four it is from where your repository stands,
prints it (mode: declare, mode: epic, mode: final or mode: remove) and goes as far as your level allows:- Finishing. The agent finishes an epic only when you say every phase is in.
- The version. A feature epic’s final pull request merges the finished feature without
touching the version;
jig spec shiprefuses one that raises it. The release comes after, made apart by thejig-releaseskill (below). An epic thatjig-releasedeclared as a release carries aRelease:line with the level you chose, and its final pull request raises the version by it. - Merging. Only an unattended run at
merge(autopilot.git, oragent.gitwhen that is not set) merges an epic’s final pull request — with a merge commit, once CI passed and every roadmap item is done. On a release epic it never merges amajorrelease, which it opens as a draft for you, andrelease.merge: humanin.ai/config.local.yamlleaves even that merge to you. - A release. A pull request whose change raises the version into the default branch —
VERSION, or theversionofpackage.json,composer.json,pyproject.tomlorCargo.tomlat the repository’s root — is a release, andjig task shipmerges it by the same rule: only in an unattended run, only withrelease.merge: agent, never amajorone, which it opens as a draft. It says so:task ship: this change raises the version in package.json: 1.4.0 -> 1.5.0. - Release notes cover everything they release. The task that writes a release’s notes records
which commit of the default branch they describe (
jig task set <id> notes_through <sha>), andjig task shipwrites it into the commit asRelease-Notes-Through: <sha>. From levelpr, a release is refused before anything is sent while the default branch has commits after it — work merged after the notes were written would otherwise reach the release undescribed — and checked again right before a merge. When it is refused, describe what came in, record the new tip and ship again. - Protected epic branches. The epic is never pushed to after it is cut: the finish goes on a
branch cut from it,
finish/<id>, and the pull request into main comes from there, so a repository that protectsepic/*like main needs no bypass.
jig spec ship keeps the limits of jig task ship below: it never force-pushes or skips hooks,
never merges a spec reaching main or a spec’s removal, merges the epic only as above, commits only what was staged, and refuses when task notes or runtime files are staged. A spec
reaching main is committed on a branch of its own, never on main itself, and may stage nothing but
the spec. The epic is pushed only as a fast-forward: when someone else moved it on the server, the
push is refused and the agent tells you. The final pull request is refused until the epic holds the
latest main.Try the result and ask for changes
Check the behaviour you asked for. For example, open the class schedule and try making a booking. If something is wrong, tell the agent what you did, what happened, and what you expected:For developers: updating a pull request and closing the task
For developers: updating a pull request and closing the task
jig task ship again: it commits the fix, pushes it, and reports the
pull request that is already open instead of opening a second one.After you merge, the task is not closed yet — a fix may still follow. At the start of a later
session the agent names the merged task and asks whether it can be closed. Nothing is closed
without your yes.Two GitHub accounts
If you are signed in togh with more than one account — a work one and a personal one, say —
gh answers as whichever is active, on the whole machine. Jig does not depend on that. For each
project it finds the one account of yours that may push to the repository and uses it for the pull
request, the checks, the merge and a push over HTTPS, whichever account gh has active. It never
switches accounts, so a session in another project is not disturbed, and your agent does not ask
you to switch either.
jig status shows the account it found:
.ai/config.local.yaml:
jig in front:
jig gh pr list.
For developers: what it covers and what it does not
For developers: what it covers and what it does not
- Each
ghcall gets that account’s stored token for the call only (gh auth token --user, gh 2.40 or later). Nothing is written to gh’s configuration. - A
GH_TOKENorGITHUB_TOKENalready in the environment wins over everything, as it does forghitself, so CI and a project.envrckeep working. It also wins when you did not mean it to: a tool started from another project’s directory inherits that directory’sGH_TOKEN. When GitHub refuses to open a pull request (“must be a collaborator”), the failure names the account Jig asked as and where it came from —github.account, the one found, or a token in the environment, with the variable to remove. - Pushing and fetching over HTTPS go as the same account — the one you named, the one Jig found
among several, or the only one
ghholds: for each of thosegitcalls, Jig sets aside your credential helper for that host and hasgitaskghfor that account’s token. Nothing is stored in your helper or in git’s configuration. If your helper held another GitHub user’s credentials, the push now goes as theghaccount instead; aGH_TOKENin the environment, or an SSHorigin, leavesgitas it was. Over SSH your key decides the account. - When several accounts may push, the active one is not among them and none is named, a ship
stops before its push and says how to name one; nothing is sent. Over HTTPS that holds at every
agent.gitlevel; over SSH only atprandmerge, where the pull request needs an account — atpushyour key decides. - A push that changes a file under
.github/workflowsneeds theworkflowscope on that account’sghtoken.gh auth refresh -s workflowadds it to the active account only; for another one, make it active for that one command withgh auth switch --user <login>, then switch back, while no other session is working — the active account is the whole machine’s. Jig itself never switches, and your agent never asks you to. jig pr fetch, which reads a colleague’s pull request, still fetches as your credential helper answers.- The choice is remembered in
.ai/runtime/gh-account; delete the file to have Jig look again.
When the agent cannot finish
It should tell you what stopped it and what needs to happen next. That might mean fixing a failed check, getting a person’s approval, or completing a setup step.For developers: enforced limits of jig task ship
For developers: enforced limits of jig task ship
- it never force-pushes and never skips your Git hooks, and it merges only at
merge, only on green checks and never past your repository’s protection; - it commits what was staged; with nothing staged it stages the changes to files Git already tracks and lists them, so the change goes out with the ship instead of staying in the folder;
- it never stages a new file for you: with nothing staged, a new file that is neither staged nor
in
.gitignoreis a refusal that names it — a secret or a scratch file pushed to your forge cannot be taken back. The commit message and pull request body files do not count; - when something is staged, that is the commit, and it names every change it left out. At
merge, with no person between the commit and your main branch, it refuses instead, committing nothing, until the rest is staged or--partialsays the rest is not this task’s; - it refuses when the branch has no commit your main branch does not, before it pushes anything or asks your forge for a pull request;
- it refuses, changing nothing, until the task’s knowledge decision is recorded;
- it refuses on any branch but the task’s own, and on the main branch itself;
- it refuses when task notes (
.ai/workspace/) or Jig’s runtime files (.ai/runtime/) are staged — those never leave your machine.
none it does nothing at all, and the
agent tells you the change is ready for your review.Turn it off
To return to the default, say:For developers: reset the local settings
For developers: reset the local settings
none — applies again; setting agent.git: none explicitly
does the same thing. The next task ends in your working tree again. The same command takes back
autopilot.git and autopilot.unattended, and jig config show --local prints what is left
(Configuration).