v0.2 Codex / Local Coding Quickstart

This file is retained for early-alpha compatibility. For the current agent-neutral interface, use ACTUAL_CODER_QUICKSTART.md. The preferred user-facing command from alpha.5 onward is actual-coder. codingagent remains a compatibility alias.

This guide uses the new gitlab-agent CLI directly from your Mac/Linux host. It does not use OpenAI model APIs.

1. Switch to the v0.2 development branch

git checkout v0.2.0-dev
git pull
uv sync

Verify:

uv run gitlab-agent --help

Recommended: install globally for Codex

bash scripts/install_user.sh

mkdir -p ~/.config/gitlab-agent
cp .env ~/.config/gitlab-agent/.env
chmod 600 ~/.config/gitlab-agent/.env

Now gitlab-agent works from the generated worktree or any other directory:

gitlab-agent --help
gitlab-agent config

Configuration resolution order is:

1. GITLAB_AGENT_ENV_FILE, if explicitly set;
2. ~/.config/gitlab-agent/.env;
3. .env in the current directory.

2. Configure the project allowlist

Copy/update .env:

GITLAB_BASE_URL=http://gitlab.example.internal

# ChatGPT read MCP token
GITLAB_TOKEN=glpat_READ_ONLY_TOKEN

# Optional separate Git credential.
# Needs write_repository for push / push-mr.
GITLAB_GIT_TOKEN=glpat_GIT_WRITE_TOKEN
GITLAB_GIT_USERNAME=oauth2
GITLAB_GIT_TRUST_ENV=false

# Required by default for v0.2 workspaces
GITLAB_ALLOWED_PROJECTS=team/project-a,team/project-b

GITLAB_WORKSPACE_ROOT=~/.local/share/chatgpt-gitlab-mcp
GITLAB_BRANCH_PREFIX=chatgpt/

If your existing GITLAB_TOKEN itself already has Git write_repository, GITLAB_GIT_TOKEN may be omitted, but separating the credentials is safer.

GITLAB_GIT_TRUST_ENV=false is especially useful on Macs that run a system/SOCKS proxy: clone/fetch/push to an internal GitLab will bypass proxy environment variables and Git's http.proxy setting.

3. Create an isolated workspace

Basic form:

gitlab-agent create team/project-a \
  --base-ref main \
  --task fix-timeout

For Codex, the new task helper is more convenient:

gitlab-agent task team/project-a \
  --base-ref main \
  --task fix-timeout \
  --goal "Fix the request timeout bug and add regression coverage"

It creates the workspace and returns the worktree path, a codex launch command, and a ready-to-paste Codex instruction block.

The JSON output includes:

{
  "workspace_id": "a1b2c3d4e5f6",
  "project": "team/project-a",
  "branch": "chatgpt/fix-timeout-a1b2c3d4",
  "worktree_path": ".../worktrees/a1b2c3d4e5f6"
}

Save the workspace_id.

4. Inspect/edit

uv run gitlab-agent status a1b2c3d4e5f6
uv run gitlab-agent files a1b2c3d4e5f6 src
uv run gitlab-agent read a1b2c3d4e5f6 src/example.py

Apply a patch:

cat fix.patch | uv run gitlab-agent apply-patch a1b2c3d4e5f6

Or replace a complete file:

cat src/example.py.new | \
  uv run gitlab-agent write a1b2c3d4e5f6 src/example.py

5. Run build/tests

Example:

uv run gitlab-agent run a1b2c3d4e5f6 -- uv run pytest

The first executable must be in GITLAB_ALLOWED_EXECUTABLES.

The runner deliberately does not allow arbitrary bash -c by default.

6. Review the diff

uv run gitlab-agent diff a1b2c3d4e5f6

Do this before commit/push.

7. Commit

uv run gitlab-agent commit a1b2c3d4e5f6 \
  -m "Fix timeout handling"

If Git cannot determine your author identity, configure it normally with Git or set:

GITLAB_GIT_AUTHOR_NAME="Your Name"
GITLAB_GIT_AUTHOR_EMAIL="you@example.com"

8. Push + create an MR

If you want an MR, prefer push-mr as the first push:

cat > /tmp/mr.md <<'EOF'
Fix timeout handling and add regression coverage.
Tests: uv run pytest
EOF

uv run gitlab-agent push-mr a1b2c3d4e5f6 \
  --target main \
  --title "Fix timeout handling" \
  --description-file /tmp/mr.md

GitLab MR creation is requested through Git push options, so the happy path only needs Git write_repository, not a broad API write token.

If you call gitlab-agent push first, v0.2 alpha will not later create the MR automatically without a broader API integration; create it manually in that case.

9. Iterate on an existing MR

Real fixes usually need more than one commit. After push-mr creates the MR, keep the workspace instead of cleaning it up.

Resume later:

gitlab-agent resume <workspace-id> \
  --goal "Address review feedback and rerun tests"

After editing/testing again:

gitlab-agent diff <workspace-id>
gitlab-agent commit <workspace-id> -m "Address review feedback"
gitlab-agent push-update <workspace-id>

push-update pushes the same feature branch. GitLab automatically updates the existing MR.

10. Recover after local cleanup / on another machine

If the local workspace was deleted but the remote feature branch still exists:

gitlab-agent checkout-branch \
  team/project-a \
  chatgpt/fix-timeout-a1b2c3d4 \
  --base-ref main \
  --goal "Continue the existing fix"

For a GitLab Merge Request, the easiest form is:

gitlab-agent checkout-mr team/project-a 123 \
  --goal "Address review feedback"

checkout-mr reads the MR metadata using GITLAB_TOKEN, resolves its source and target branches, reconstructs a managed worktree from the existing remote source branch, remembers the MR URL, and returns a Codex handoff prompt.

For safety, reconstructed source branches must use the configured GITLAB_BRANCH_PREFIX (default chatgpt/). Cross-project/fork MRs are not yet supported.

After editing/testing/committing:

gitlab-agent push-update <workspace-id>

This updates the same remote branch and therefore the same existing MR.

11. Cleanup

After the branch is pushed/MR exists and the task is truly finished:

uv run gitlab-agent cleanup a1b2c3d4e5f6

The command refuses to discard dirty work or unpushed commits unless:

uv run gitlab-agent cleanup a1b2c3d4e5f6 --force

12. Suggested Codex prompt

From this repository or from a working directory where Codex can invoke the CLI:

Use the gitlab-agent CLI for workspace lifecycle and Git operations. Create a workspace for team/project-a from main with task fix-timeout. Investigate the bug, make the smallest correct change, run the relevant tests, inspect the final diff, and only if tests pass commit and call push-mr targeting main. Do not use an OpenAI API key or any model API.

Codex may directly edit files inside the returned worktree_path; the CLI remains useful for isolation, status, tests, branch policy, commit, push, and MR creation.

Current alpha limitations

• Host command execution is constrained but not container-sandboxed.
• MR creation is optimized for first push.
• No merge/approve/force-push/delete-remote operations.
• No arbitrary shell execution.