github

A change you make in a workspace lives on its own branch on your Mac. The GitHub panel takes it further. It pushes the branch to your own fork of ixi, proposes it to ixi as a pull request, and replays your changes when a newer ixi comes out.

In the menu bar choose Customize → Customize ixi…, then GitHub under ixi in the sidebar.

connect GitHub

The Account card offers two ways in.

Use my GitHub CLI login reuses the login of the GitHub CLI (gh), if you have it installed and signed in:

1. Press Use my GitHub CLI login. ixi finds gh and asks it which account is signed in.
2. The card asks "The GitHub CLI is signed in as @you. Use that login for ixi?" Press Use @you, or Not now.
3. The card shows Signed in as and your GitHub name, with "Using your GitHub CLI login. The token is encrypted in your Keychain."

ixi reads the CLI's token only after you agree. It checks the token with GitHub, then keeps a copy, encrypted in your Keychain, until you disconnect. If gh isn't found, or isn't signed in, the card says so; run gh auth login in Terminal and try again.

Sign in with GitHub signs in through your browser with a one-time code. The card shows the code with Open github.com/login/device, Copy code and Cancel, and waits while you approve ixi Desktop on GitHub.

The login must be allowed to fork and open pull requests on public repositories (GitHub's public_repo permission). A login without it is refused when you connect.

Disconnect deletes ixi's copy of the token. Your gh login itself is untouched.

pick a workspace

Once you're connected, Workspace lists your source (as source) and every workspace, each with its branch. Everything below acts on the one you pick.

fork ixi

Press Fork ixi-design/ixi. ixi makes your fork on GitHub, or finds the one you already have, and waits for GitHub to finish making it. The card then shows "Your fork: you/… — ixi pushes only there."

Forking also sets up git in your source and every workspace: origin points at your fork, upstream points at ixi, and ixi's latest branches and tags are fetched. If a checkout is missing upstream, the card says "This checkout has no upstream remote yet." Press Set up remotes.

push to your fork

The Push card shows the workspace's branch, how many commits it is ahead of ixi, and whether it's pushed.

• Only commits are pushed. With uncommitted changes, the card warns "There are uncommitted changes; only commits are pushed." Commit them, or ask your agent to.
• Every commit needs a sign-off. ixi accepts a change only when each commit carries a DCO Signed-off-by: line with its author's email. The card lists the commits without one. Add sign-off (git rebase --signoff) adds your sign-off to every commit on the branch. It needs a branch with no uncommitted changes. If git has no email set, ixi sets this repository to sign off with your GitHub no-reply address.
• Push to my fork pushes the branch to a branch of the same name on your fork. It stays greyed out until the branch has commits ixi doesn't, every commit is signed off, and no rebase is in progress. You'll see "Pushed" and the branch and fork.

If your fork's branch has commits this one doesn't, for example after you bring changes forward, the push is refused and Force-push (with lease) appears. It replaces the fork's branch, but only if the fork still has what ixi pushed last.

propose to ixi

1. Press Draft pull request. ixi fills in a title (the commit message for one commit, otherwise the branch name) and a description: a summary, the commits, the files changed, and ixi's pull request template if the repository has one.

2. To have your agent write the description, press Draft the description with my agent. ixi writes the request to .context/pr-request.md in the workspace, and the agent answers in .context/pr-description.md. If an agent is running in the workspace's terminal, ixi also types one line there: "Read .context/pr-request.md and do what it asks (write the pull request description to .context/pr-description.md)."

   • The agent is at its prompt: ixi types the line and presses Enter.
   • The agent printed something in the last 1.5 seconds: ixi types the line but doesn't press Enter, so it doesn't interrupt. Press Enter there when it has finished.
   • You have something typed on its line, or it's waiting for your answer (an approval or a question): ixi types nothing. Ask it to read the file yourself.
   • No agent is running: ixi types nothing. Start one with Start agent and ask it to read the file.

   The card says which of these happened. When the agent has answered, press Use the agent’s draft.

3. Edit the title and description. Open as a draft is ticked to start with.

4. Press Propose to ixi. It opens a pull request from your fork's branch to ixi's main, and the card links to it: "Pull request #… opened as a draft". If one is open already, the card links to that instead.

Propose to ixi needs the branch pushed first, because the pull request shows what is on your fork. Discard drops the draft.

bring changes forward

When a newer ixi comes out, Bring changes forward replays your branch on top of it: ixi fetches ixi's latest, then rebases your branch onto main or a release tag.

1. Commit everything first. A workspace with uncommitted changes is refused.
2. Type main, or a release tag such as v1.2.0, and press Bring my changes forward.
3. You'll see one of:
   • "… now sits on …": done.
   • "… already contains …": nothing to do.
   • These files conflict, with the list of files. ixi writes them to .context/rebase-conflicts.md for your agent, with what to do, and asks a running agent in its terminal to resolve them, the same way as the description. Once the agent has resolved and staged them, press Continue. More conflicts may follow, one commit at a time. Abort puts the branch back exactly as it was.
4. Your branch has moved, so your fork refuses the next plain push: press Force-push (with lease) when it appears. If you run this workspace as a build, use it again to get the result.

Bring your changes forward in the Builds panel does the same for a build's workspace, onto main.

limits & good to know

• One GitHub action per workspace at a time. A second one is refused until the first finishes.
• Only pushes and pull requests use your login. Fetching from ixi is anonymous, because the repository is public.
• Your token stays out of the workspace. It never lands in a workspace's git settings, and the workspace's git hooks don't run on a push from this panel.
• Forking can take a while. ixi waits up to 5 minutes for GitHub to finish; after that, try again in a minute.
• A pull request title is 1–256 characters, and a description at most 65,000.

related

• customize ixi: make a change in a workspace with your agent.
• builds and safe mode: run ixi as built from a workspace.