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

Core API Usage

Setting Up Authentication

[!CAUTION] NEVER commit your GITBUCKET_TOKEN to the repository. Retrieve it from your secure credentials vault and set it as an environment variable locally.

Set the required environment variable before running scripts or curl:

export GITBUCKET_TOKEN="<YOUR_TOKEN_FROM_VAULT>"

Preferred Utilities (Python)

Use these pre-parameterized scripts to avoid repetitive curl syntax:

1. Create an Issue

python .agent/utils/gitbucket/create_issue.py \
    --title "Feature: [Name]" \
    --body "Goal: ... \n\n### Tasks: \n- [ ] Task 1"

2. Add a Comment / Progress Update

python .agent/utils/gitbucket/add_comment.py \
    --issue <ISSUE_NUMBER> \
    --body "### Status Update\nCompleted Step 1."

Raw API (Alternative)

Use curl for direct queries or when scripts are unavailable:

curl -H "Authorization: token $GITBUCKET_TOKEN" \
     https://gitbucket.jerxie.com/api/v3/repos/yangyangxie/cortex-hub/issues

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 via API. Note: The GitBucket API often returns 404 Not Found for PATCH requests on issues; therefore, you MUST use the browser_subagent to manually click "Close issue" in the UI to finalize the task.

4. UI-Only Actions (Browser Setup)

Required when API limitations (like closing issues) prevent task completion.

// 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.

UI Selector Cheat Sheet

Use these stable selectors to avoid re-analyzing the DOM:

• Login Page:
  • Username: input[name="userName"]
  • Password: input[name="password"]
  • Submit: input[type="submit"]
• Issue Page:
  • Comment Area: textarea[name="content"]
  • Close Issue Button: .btn.btn-danger (sometimes labeled "Close issue")
  • Comment Button: .btn.btn-success (sometimes labeled "Comment")
  • Issue Status Label: .label-success (Open), .label-important (Closed)

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).