---
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`:
```bash
export GITBUCKET_TOKEN="<YOUR_TOKEN_FROM_VAULT>"
```

### Preferred Utilities (Python)
Use these pre-parameterized scripts to avoid repetitive `curl` syntax:

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

#### 2. Add a Comment / Progress Update
```bash
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:
```bash
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:
```bash
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:
```bash
# 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)
```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.
```bash
# 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.
```bash
# 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:
```bash
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).
