Skip to content

write-walkthrough.md

Latest commit

 

History

History
306 lines (229 loc) · 10.4 KB

write-walkthrough.md

File metadata and controls

306 lines (229 loc) · 10.4 KB
Raw

Write Walkthrough

Issue identity selectors

Issue write commands accept either --number, meaning the repository-local GitCode issue number, or --issue-id, meaning a stable source id or known cached alias:

gitcode-mcp add-issue-comment \
  --repo example-owner/example-repo \
  --issue-id ISSUE-76 \
  --body "Design reviewed" \
  --idempotency-key issue-76-design-reviewed

Aliases such as issue:76 and a cached gitcode_issue_id:... are also accepted. Resolution stays cache-first; sync the issue before using an uncached alias. Do not pass a provider id as --number. If the cache can prove that a numeric value is a provider or stable id rather than an issue number, the command fails before mutation and reports the correct issue_number and stable_source_id.

This walkthrough covers the explicit, gated write path for GitCode operations.

Write safety principles

  • Writes execute live by default for configured repositories.
  • --dry-run validates the operation without making any mutation.
  • --live remains accepted as a compatibility alias for live writes.
  • No write can succeed without reaching the remote adapter.
  • Idempotency keys prevent duplicate writes.

The legacy add-comment command is a fail-closed migration guard: it never writes and tells the caller to choose add-issue-comment or add-pr-comment. This prevents an issue/PR number collision from silently selecting the wrong target.

Multiline Markdown bodies

For multiline issue and issue-comment Markdown, use a UTF-8 file or stdin instead of shell-escaped inline text:

gitcode-mcp add-issue-comment \
  --repo example-owner/example-repo \
  --number 42 \
  --body-file ./comment.md \
  --idempotency-key issue-42-comment

gitcode-mcp update-comment \
  --repo example-owner/example-repo \
  --comment-id 2002 \
  --body-file - \
  --idempotency-key comment-2002-update < ./comment.md

create-issue, update-issue, add-issue-comment, add-pr-comment, and update-comment accept at most one of --body or --body-file; comment writes still require a non-empty body, while issue writes may omit it. --body-file - reads stdin. File/stdin inputs are bounded to 10 MiB and must be non-empty valid UTF-8. CRLF and lone CR line endings normalize to LF; all trailing newlines are otherwise preserved. The CLI never unescapes backslashes.

An inline body containing two or more literal \n sequences and no real newline fails before service startup or an external write. Use --body-file for intended Markdown, or --allow-literal-backslash-n when those literal characters are intentional. Dry-run output exposes only safe input metadata—source, byte count, real-newline count, literal-\n count, and normalization flags—not the body itself.

Dry-run mode

All write commands support --dry-run for pre-flight validation.

Create issue (dry-run)

gitcode-mcp create-issue \
  --repo example-owner/example-repo \
  --title "Test issue" \
  --body "This is a test issue body." \
  --labels bug,needs-triage \
  --milestone MILESTONE-1 \
  --dry-run

Expected: reports what would be created without making any mutation. Cache and remote are unchanged.

Update issue (dry-run)

gitcode-mcp update-issue \
  --repo example-owner/example-repo \
  --number 42 \
  --state closed \
  --clear-milestone \
  --dry-run

Expected: reports what would be updated without making any mutation. --milestone ID_OR_TITLE assigns a milestone; --clear-milestone clears it, and the two flags are mutually exclusive.

Create pull request / merge request (dry-run)

gitcode-mcp create-pr \
  --repo example-owner/example-repo \
  --title "Add cache-first PR flow" \
  --body "Summary and tests." \
  --head feature-branch \
  --base main \
  --dry-run

Expected: reports what would be created without making any mutation. create-mr is an alias for users who follow GitCode UI terminology.

Milestones (dry-run)

gitcode-mcp create-milestone \
  --repo example-owner/example-repo \
  --title "RAG indexer MVP" \
  --description "Implementation milestone" \
  --due-on 2026-07-15 \
  --dry-run

Expected: validates milestone creation without mutation. GitCode requires --due-on for milestone creation.

gitcode-mcp set-issue-milestone \
  --repo example-owner/example-repo \
  --number 42 \
  --milestone "RAG indexer MVP" \
  --dry-run

Expected: validates issue milestone assignment. Live set-issue-milestone and clear-issue-milestone verify the result through issue readback because GitCode can return a stale or null milestone in the immediate PATCH response.

The generic create-issue and update-issue commands use the same resolver and readback contract. A milestone selector may be a numeric remote id, stable MILESTONE-<id>, or exact title. Live receipts include the resolved stable id, remote id, and title; clear operations include an explicit cleared marker. For partial update-issue writes, omitted milestone and labels mean preserve, not clear. The adapter reads the live preimage to work around the provider's omitted-milestone behavior and accepts success only after canonical readback matches every requested field and the unrelated fields remain unchanged. Before PATCH, the service durably claims the idempotency key against hashes of that canonical preimage. A timeout after PATCH or during readback is therefore not a normal retry: the next same-key call performs GET-only recovery. It returns recovered_after_ambiguous_write when requested and preserved fields match, write_ambiguous_remote when they do not, or write_conflict when a safely retryable attempt sees that its previously captured preimage changed.

Create wiki page (dry-run)

gitcode-mcp create-page \
  --repo example-owner/example-repo \
  --slug New-Page \
  --title "New Wiki Page" \
  --body "Page content here." \
  --dry-run

Expected: reports what would be created.

Add issue comment (dry-run)

gitcode-mcp add-issue-comment \
  --repo example-owner/example-repo \
  --number 42 \
  --body "This is a test comment." \
  --dry-run

Expected: reports what would be added.

Add pull request comment (dry-run)

gitcode-mcp add-pr-comment \
  --repo example-owner/example-repo \
  --number 17 \
  --body-file ./pr-comment.md \
  --dry-run

Expected: reports target_kind: pull_request, target number 17, and a credential-free browser URL without making a mutation. Issue-comment dry-runs analogously report target_kind: issue.

Update comment (dry-run)

gitcode-mcp update-comment \
  --repo example-owner/example-repo \
  --comment-id 2002 \
  --number 42 \
  --body-file ./updated-comment.md \
  --dry-run

Expected: reports what would be updated. --number is optional for the live GitCode route, but it helps the local cache resolve the parent issue deterministically.

Live mode

Live mode is the default for write commands and requires:

  1. GITCODE_TOKEN environment variable set
  2. Network access to the GitCode API
  3. no explicit --dry-run

Create issue (live)

gitcode-mcp create-issue \
  --repo example-owner/example-repo \
  --title "Test issue" \
  --body "Test body." \
  --labels bug \
  --idempotency-key "issue-create-001"

Expected: issue is created on the remote, audit row is written, cache is refreshed.

Update issue (live)

gitcode-mcp update-issue \
  --repo example-owner/example-repo \
  --number 42 \
  --title "Updated title" \
  --state closed

Expected: issue is updated on remote, audit row recorded, cache refreshed.

The public CLI and MCP state values are open and closed. The GitCode adapter translates them to the write-only transition events reopen and close, then requires issue readback with the requested public state. A state-only update does not send title, body, labels, milestone, or assignee fields.

Create pull request / merge request (live)

gitcode-mcp create-pr \
  --repo example-owner/example-repo \
  --title "Add cache-first PR flow" \
  --body "Summary and tests." \
  --head feature-branch \
  --base main \
  --idempotency-key "pr-create-001"

Expected: pull request is created on remote, audit row recorded, cache refreshed. Use create-mr as an equivalent alias when matching GitCode UI language.

Create wiki page (live)

gitcode-mcp create-page \
  --repo example-owner/example-repo \
  --slug New-Page \
  --title "New Page" \
  --body "Content."

Expected: wiki page created on remote, audit row recorded, cache refreshed.

Add issue comment (live)

gitcode-mcp add-issue-comment \
  --repo example-owner/example-repo \
  --number 42 \
  --body "Comment text."

Expected: comment added on remote, audit row recorded, cache refreshed.

Add pull request comment (live)

gitcode-mcp add-pr-comment \
  --repo example-owner/example-repo \
  --number 17 \
  --body "PR comment text." \
  --idempotency-key pr-17-comment

Expected: comment added to pull request 17 on remote, audit row recorded, cache refreshed, and the receipt identifies target_kind: pull_request.

Update comment (live)

gitcode-mcp update-comment \
  --repo example-owner/example-repo \
  --comment-id 2002 \
  --number 42 \
  --body-file ./updated-comment.md

Expected: existing issue comment updated on remote through PATCH /api/v5/repos/{owner}/{repo}/issues/comments/{comment_id}, audit row recorded, and the cached record_comments row upserted instead of duplicated.

Idempotency

Idempotency keys prevent duplicate writes. If a write with the same key is retried:

  • The audit trail shows the prior successful write.
  • A duplicate is not created on the remote.
  • The command reports success and references the prior audit row.

Error handling

Write failures produce typed errors:

Error class Description
adapter_unavailable GitCode adapter cannot process the request (no token, no network)
remote_error Remote API returned an error
conflict Remote state conflicts with the requested change
audit_failure Write succeeded on remote but audit row could not be recorded
validation_error Request parameters are invalid

The command exit code reflects the error class. Error messages do not expose tokens or private data.

Fixture-mode write walkthrough

When running without live credentials, write commands in --dry-run mode validate against the fixture cache without network access. This is the default behavior for the docs smoke tests.