Git and GitHub

Which of the ten modes touch git and how, forward-style branch naming and commit rhythm, deterministic git repair, and how credentials are kept out of the repository history.

A
Written By Atakan KayaLast updated 3 months ago

Git and GitHub

LEX AI treats git as infrastructure the server owns — not something the assistant improvises. Which modes touch git, and how, is fully deterministic, so a run cannot end with commits you did not expect on a branch you did not choose.

Who touches git

Mode

Local commits

Pushes

Branches

PRs

Forward

Yes

Yes

Yes

Yes

MVP Completion

Yes

Yes

Yes

Yes

MVP Generator

Yes (local only)

No

No

No

Brief

No

No

No

No

Backward

No

No

No

No

Edit

Yes

Yes

Yes

Yes — never merges

Review

No

No

No

No

Test

No

No

No

No

Input

No

No

No

No

Deploy

No

No

No

No

Forward, MVP Completion and Edit reach GitHub. Backward, Review, Test and Input may run git clone when you pass a repository URL, but they never commit, branch, push or open a PR — their output is left in the working tree for you to read and commit yourself.

Edit is the newest of the three and behaves differently from the other two on purpose: it opens a pull request and stops there. Forward and MVP Completion merge because they own the whole branch; several edit runs can be open on one base at once, so merging one would land its work underneath another still building on it.

Deploy is git-free deliberately rather than by omission: a deployment run writes configuration, and an automatic commit is precisely how a populated .env would reach a remote.

Forward-style git (Forward, MVP Completion)

  • The server owns every git operation — the coordinator is instructed never to run git itself, because manual branch switching mid-run misplaces commits the manifest is still tracking.
  • Authentication — GITHUB_TOKEN or COPILOT_GITHUB_TOKEN, read from the server environment or the project .env.
  • The workflow remote defaults to lex-origin (override with LEX_MCP_WORKFLOW_REMOTE), stored as a token URL so pushes are non-interactive.
  • Prompts are disabled — GIT_TERMINAL_PROMPT=0, an empty GIT_ASKPASS and GCM_INTERACTIVE=never, so an MCP session can never hang invisibly on a credential dialog. Command output is redacted before it is logged.

Branch naming

Workflow branches are <repo-or-requested-name>/run-NN, zero-padded and auto-incremented from the branches already on the remote — first run-00, then run-01, and so on. kickstart_workflow uses the requested repo name as the prefix, kickstart_run uses the repo argument, and resume_workflow finds the highest existing run-NN and treats it as active.

The commit and push rhythm

  • kickstart_workflow creates the repo, writes .gitignore and AGENTS.md, commits everything, pushes the default branch, then creates the run branch and a tracking issue.
  • notify_step_complete commits the worktree as [step-NN/<process>] <summary> and pushes the run branch, recording the changed files in the manifest.
  • If you edit earlier-step files between steps, get_plan_step commits them as [user-feedback] ..., pushes, and re-runs from the earliest affected step.
  • finalize_workflow(audit_complete=True) commits and pushes what remains, opens a PR from the run branch, squash-merges it, checks out and pulls the default branch, and closes the tracking issue.

Keeping credentials out of the history

The project-scoped MCP configs hold GITHUB_TOKEN and REMOTE_MCP_API_KEY, and the forward workflow stages and pushes everything. Setup therefore writes a managed .gitignore block covering those configs and the generated payload. An ignore rule cannot untrack a file that is already committed, so setup also lists which of its own entries are in the index and tells you to git rm --cached them and rotate anything exposed. CLAUDE.md, AGENTS.md and .lex/contract.md stay tracked on purpose — they carry your prose and your requirements.

In Deploy, the rule is stricter and non-waivable: a secret value is never written into a step record, an index row, the report or a log line, only the key name and where it belongs. A credential found already committed is a halt, not a finding.

Deterministic git repair

The server auto-repairs a small, known set of failures: a stale .git/index.lock, a missing upstream on push, a non-fast-forward push, branch-already-exists on checkout, a missing local branch, and unrelated histories on pull or fetch. The retry budget is GIT_MAX_REPAIR_ATTEMPTS (default 3). When repair is exhausted the tool returns ok: false and the assistant stops and shows you the troubleshooting rather than forcing it. See Troubleshooting.

MVP Generator: local git only

git init -b main on kickstart if needed, a best-effort commit per checkpoint, never a remote and never a push. Set LEX_MVP_NO_GIT=1 to disable local commits; git failures there are warnings, not blockers. See MVP workflows.

Was this helpful?

Your feedback shapes what we write next.