description: How to manage GitBucket repository resources (Issues, PRs, Content) using the API

Overview

GitBucket provides a GitHub v3 compatible API at https://gitbucket.jerxie.com/api/v3. Antigravity AI uses a Personal Access Token to authenticate.

Core API Usage

Setting Up Authentication

The token must be provided in the Authorization header: Authorization: token <YOUR_TOKEN>

Examples:

1. Create an Issue

curl -H "Authorization: token <TOKEN>" \
     -X POST -d '{"title": "Issue Title", "body": "Issue Description"}' \
     https://gitbucket.jerxie.com/api/v3/repos/yangyangxie/cortex-hub/issues

2. Create a Pull Request

curl -H "Authorization: token <TOKEN>" \
     -X POST -d '{"title": "PR Title", "base": "master", "head": "feature-branch", "body": "PR Description"}' \
     https://gitbucket.jerxie.com/api/v3/repos/yangyangxie/cortex-hub/pulls

3. List Releases

curl -H "Authorization: token <TOKEN>" \
     https://gitbucket.jerxie.com/api/v3/repos/yangyangxie/cortex-hub/releases

Using Snippets (Gists) as a Secret Store

GitBucket's Snippet feature works primarily via Git or Raw Web Access. The standard GitHub JSON API for gists is currently not active on this instance.

Accessing Secrets (Read)

Use curl to fetch raw file content directly:

curl -L https://gitbucket.jerxie.com/gist/yangyangxie/<ID>/raw/master/<FILENAME>

Manipulating Secrets (Write/Update)

Every Snippet is a standard Git repository. You can clone, edit, and push changes back:

# Clone the snippet
git clone https://yangyangxie:<PAT>@gitbucket.jerxie.com/git/gist/yangyangxie/<ID>.git secret-repo

# Update secret
cd secret-repo
echo "new-secret-value" > config.json
git add . && git commit -m "update secret"
git push origin master

Snippet Vault Pattern

Use a Private Snippet as a simple "Vault" for your project.

Implementation Example (Bash)

# Pull and source secrets
GITBUCKET_TOKEN="YOUR_TOKEN"
SNIPPET_ID="YOUR_SNIPPET_ID"
TMP_DIR=$(mktemp -d)
git clone "https://user:${GITBUCKET_TOKEN}@gitbucket.jerxie.com/git/gist/user/${SNIPPET_ID}.git" "$TMP_DIR"
source "$TMP_DIR/.env"
rm -rf "$TMP_DIR"

AI Service Credentials Vault

Store AI provider keys (Gemini, DeepSeek, OpenAI) in a dedicated private snippet (e.g., .env.ai).

• Snippet ID: 6f583b2e0a6b7297970648c0c323e81d
• Keys Included: DEEPSEEK_API_KEY, GEMINI_API_KEY, OPENAI_API_KEY, EMBEDDING_API_KEY, OIDC_CLIENT_SECRET.

AI Project Management & Task Orchestration

Since some GitBucket API features (like Search and Patch) are limited, use this "Audit Log" pattern for AI-driven development:

1. Feature Initiation (Create Issue)

Start every complex task by creating an issue. This provides a central ID for all future actions.

# Create the task
curl -H "Authorization: token <TOKEN>" \
     -X POST -d '{"title": "Feature: [Name]", "body": "Goal: ...\n\n### Tasks:\n- [ ] Step 1\n- [ ] Step 2"}' \
     https://gitbucket.jerxie.com/api/v3/repos/owner/repo/issues

2. Progress Documentation (Comments)

Instead of updating the issue body (unsupported), add a comment for every major milestone or sub-task completion.

# Document progress
curl -H "Authorization: token <TOKEN>" \
     -X POST -d '{"body": "STT Backend logic implemented in /app/core/stt.py"}' \
     https://gitbucket.jerxie.com/api/v3/repos/owner/repo/issues/<ID>/comments

3. Orchestration Workflow

• List All: GET /api/v3/repos/owner/repo/issues to see the current backlog.
• Detailed Context: GET .../issues/<ID>/comments to read the history of an ongoing task.
• Finish: Post a final summary comment and use the browser subagent to close the issue in the UI.

4. UI-Only Actions (Browser Setup)

For actions that the API cannot handle (like closing an issue in certain configurations), use the browser_subagent.

// turbo

Establish Browser Bridge (Dev Container)

If the browser is unreachable (e.g., ECONNREFUSED 127.0.0.1:9222), ensure port 9222 is forwarded in VS Code and run:

sudo apt-get install -y socat
# Bridge container port 9222 to host machine
socat TCP-LISTEN:9222,fork,reuseaddr TCP:host.docker.internal:9222 &
# Verify connection
curl -s http://127.0.0.1:9222/json/version

Authentication

Retrieve login credentials (username/password) from the Snippet Vault (.env.ai) using the git clone or raw fetch methods described above before attempting any browser-based login.

Security Best Practices

• Private Only: Never store credentials in "Public" or "Secret" snippets.
• Rotation: Update the snippet regularly; agents will automatically pick up the new values.
• Cleanup: Always delete temporary directories used for cloning secrets.
• Token Scope: Ensure the Personal Access Token has repo and gist scopes (if applicable).