Relay GitCode CLI

Workflow

Use the selected gd binary as the GitCode control surface. Prefer --json for automation and inspect command help before exposing unfamiliar operations:

gd --help
gd pr create --help
gd api --help

Keep behavior GitCode-specific. Do not introduce GitHub-only command surfaces such as gists, codespaces, projects, GitHub Actions, rulesets, extensions, or Copilot unless GitCode exposes equivalent API behavior and the task can be done through gd api.

When gd commands, flags, examples, or user-facing behavior change in this repository, update this SKILL.md in the same change so agent workflows stay aligned with the compiled CLI.

gd reuses reqwest system proxy behavior for HTTP_PROXY/http_proxy, HTTPS_PROXY/https_proxy, ALL_PROXY/all_proxy, and NO_PROXY/no_proxy. TLS certificate verification is disabled by default for GitCode API calls.

Readiness

Select the newest usable gd before running workflows. Resolve bundled assets relative to this skill directory. On Linux x64, check assets/bin/linux-x86_64/gd; on Windows x64, check assets/bin/windows-x86_64/gd.exe. Also check the gd binary found on PATH with command -v gd on Unix or where gd on Windows.

For every candidate that exists and is executable, run \x3Ccandidate> --version and parse the semver from output such as gd 0.1.0. Use the candidate with the highest semver. If versions are equal, prefer the bundled binary. Ignore candidates that cannot run or do not print a parseable gd version. If the selected binary is not on PATH, run it by absolute path or set GD_BIN and substitute "$GD_BIN" for gd in the examples below.

Set GD_BIN to the selected path, then inspect version and authentication state:

"$GD_BIN" --version
"$GD_BIN" version check --json
"$GD_BIN" auth status --json

Only install online when no bundled or PATH binary is usable. Prefer the Rust package first and GitHub Releases second:

cargo install relay-gitcode-cli --force
gd version check --json

When falling back to GitHub Releases downloads, use the environment proxy required by the host network. Check or set HTTPS_PROXY/https_proxy, HTTP_PROXY/http_proxy, ALL_PROXY/all_proxy, and NO_PROXY/no_proxy before running curl, wget, or another downloader.

Do not install this skill by building gd from a local repository checkout. The bundled binaries and online fallbacks should come from released CLI artifacts.

For temporary CI or end-to-end tests, prefer GITCODE_TOKEN in the process environment. For interactive token login, read the token from stdin and store it in the system keyring:

printf '%s' "$GITCODE_TOKEN" | gd auth login --with-token --json
gd auth status --json

Never print, commit, or persist personal access tokens, cookies, or private API responses in repository files.

Core Workflows

Use explicit repositories with --repo owner/repo when the current directory does not define a gd default repository. Add --json for machine-readable output:

gd repo view owner/repo --json
gd repo list owner --limit 50 --json
gd repo clone owner/repo
gd repo create name --private --description "demo" --json
gd repo fork owner/repo --json
gd repo move owner/repo target-owner/new-name --json
gd repo move owner/repo target-owner --name new-name --json
gd repo sync-github coolplayagent/relay-gitcode-cli --org plm-cac --private --json
gd repo sync-github [email protected]:owner/repo.git --repo target-org/repo --if-exists skip --json
gd repo sync-github owner/repo --repo target-org/repo --method git-push --if-exists update --json

gd repo move moves a GitCode repository between users and organizations, or renames it when the target owner is unchanged. Use a disposable repository for E2E checks:

GITCODE_TOKEN=... GD_E2E_SOURCE_REPO=owner/repo GD_E2E_TARGET_OWNER=target-owner GD_E2E_TARGET_NAME=temporary-name scripts/e2e-repo-move.sh

gd repo sync-github accepts a GitHub owner/repo, HTTPS URL, or SSH URL and creates a GitCode repository with that GitHub repository as import_url by default. Without --org or --repo, it imports into the authenticated GitCode user namespace. Use --org for a GitCode organization and --repo owner/name for an explicit target path. Existing targets are skipped by default. Use --method git-push to create a regular GitCode repository and push GitHub branches and tags with Git instead of enabling Pull mirroring; this keeps the target writable for GitCode Release creation. Use --if-exists update to push refs to an existing regular target, or --if-exists recreate to delete and recreate the target.

Manage issues and pull requests with the GitCode-backed command surface:

gd issue list --repo owner/repo --state open --limit 30 --json
gd issue view 1 --repo owner/repo --json
gd issue create --repo owner/repo --title "bug" --body "details" --json
gd issue comment 1 --repo owner/repo --body "thanks" --json

gd pr list --repo owner/repo --state open --base main --json
gd pr view 1 --repo owner/repo --json
gd pr create --repo owner/repo --title "change" --body "details" --base main --head feature --json
gd pr comments 1 --repo owner/repo --limit 50 --json
gd pr comment 1 --repo owner/repo --body "please fix" --path src/main.rs --position 3 --need-to-resolve --json
gd pr reply 1 discussion-id --repo owner/repo --body "fixed" --json

Use gd api for GitCode API v5 endpoints that do not have first-class subcommands:

gd api /user --json
gd api /repos/owner/repo -X PATCH -F has_issues=true --json
gd api /repos/owner/repo/issues --paginate --json

Manage GitCode Releases and migrate published GitHub Release assets into a GitCode Release when a GitCode repository mirrors GitHub source code:

gd release list --repo owner/repo --json
gd release view v0.1.0 --repo owner/repo --json
gd release create v0.1.0 --repo owner/repo --title "v0.1.0" --notes "Release notes" --json
gd release migrate-github --repo owner/repo --github-repo source/repo --tag v0.1.0 --json
gd release migrate-github --repo owner/repo --github-repo source/repo --all --dry-run --json
gd release migrate-github --repo owner/repo --github-repo source/repo --tag v0.1.0 --update-release=false --skip-existing-assets=false --json

gd release migrate-github reads GitHub Release metadata and uploaded assets, then creates or updates GitCode Releases through GitCode Release APIs. It uses GITHUB_TOKEN when present for GitHub API reads, GITCODE_TOKEN or the system keyring for GitCode writes, and skips existing GitCode assets with matching names by default. Use --update-release=false to preserve existing GitCode Release metadata and --skip-existing-assets=false to fail on duplicate asset names.

Pipelines

GitCode workflow commands use GitCode API credentials. OpenLibing gate commands use separate OpenLibing GitCode OAuth credentials; they do not reuse GITCODE_TOKEN. Use gd pipeline auth login for browser OAuth, or set GD_OPENLIBING_TOKEN or GD_OPENLIBING_COOKIE for automation. Use the OpenLibing --project-id, not the GitCode repository id.

gd pipeline set --repo owner/repo .gitcode/workflows/ci.yml --file workflow.yml --json
gd pipeline codecheck --repo owner/repo --language SHELL --access-token-secret CODECHECK_ACCESS_TOKEN --json
gd pipeline run --repo owner/repo workflow-id --file-path .gitcode/workflows/ci.yml --branch main --json
gd pipeline runs --repo owner/repo --workflow-name ci --status success --json
gd pipeline view --repo owner/repo workflow-run-id --json
gd pipeline log --repo owner/repo workflow-run-id job-id
gd pipeline stop --repo owner/repo workflow-run-id --json
gd pipeline retry --repo owner/repo workflow-run-id --json
gd pipeline rerun --repo owner/repo workflow-run-id --json

gd pipeline auth status --json
gd pipeline config --project-id openlibing-project-id --json
gd pipeline setup --project-id openlibing-project-id --repo owner/repo --language Rust --codecheck-rule-set default --json
gd pipeline prs --project-id openlibing-project-id --repo owner/repo --state open --json
gd pipeline checks --project-id openlibing-project-id --repo owner/repo --pr 1 --json
gd pipeline gate-view --project-id openlibing-project-id --repo owner/repo --pr 1 --json
gd pipeline gate-runs --project-id openlibing-project-id --pipeline-name codecheck --json

gd pipeline checks falls back to the OpenLibing CodeCheck task summary when the CICD PR check endpoint is not readable. gd pipeline setup --codecheck-rule-set accepts either a rule-set name or a direct rule-set ID. For setup failures on OpenLibing repository add/update, check the documented OpenLibing prerequisites before retrying: project administrator or equivalent project approver role, repository recorded in Code Repository Management, PR takeover enabled, CodeCheck language/rule set selected, GitCode public or robot account repository access, and webhook configuration permission.

Troubleshooting

If a command fails, read the JSON response or the gd: error line before guessing hidden state. Check authentication, repository spelling, hostname, and API base first:

gd auth status --json
gd repo view owner/repo --json
gd api /user --json
gd --api-base https://api.gitcode.com/api/v5 api /user --json

For more command recipes, API automation patterns, and GitCode workflow YAML examples, read references/cli-workflows.md and references/gitcode-workflow-yml.md.