Initial commit
This commit is contained in:
Zhongwei Li
291
skills/buildkite-status/references/tool-capabilities.md
Normal file
291
skills/buildkite-status/references/tool-capabilities.md
Normal file
@@ -0,0 +1,291 @@
|
||||
# Tool Capabilities Reference
|
||||
|
||||
This document provides complete capability information for all Buildkite status checking tools.
|
||||
|
||||
## Overview
|
||||
|
||||
Three tool categories exist with different strengths and limitations:
|
||||
|
||||
1. **MCP Tools** - Direct Buildkite API access via Model Context Protocol
|
||||
2. **bktide CLI** - Human-readable command-line tool (npm package)
|
||||
3. **Bundled Scripts** - Helper wrappers in this skill's `scripts/` directory
|
||||
|
||||
## Capability Matrix
|
||||
|
||||
| Capability | MCP Tools | bktide | Scripts | Notes |
|
||||
| --------------------- | ------------------------------- | ----------------------- | -------------------------- | -------------------------- |
|
||||
| List organizations | ✅ `buildkite:list_orgs` | ❌ | ❌ | |
|
||||
| List pipelines | ✅ `buildkite:list_pipelines` | ✅ `bktide pipelines` | ❌ | |
|
||||
| List builds | ✅ `buildkite:list_builds` | ✅ `bktide builds` | ✅ `find-commit-builds.js` | Scripts are specialized |
|
||||
| Get build details | ✅ `buildkite:get_build` | ✅ `bktide build` | ❌ | |
|
||||
| Get annotations | ✅ `buildkite:list_annotations` | ✅ `bktide annotations` | ❌ | |
|
||||
| **Retrieve job logs** | **✅ `buildkite:get_logs`** | **❌ NO** | **✅ `get-build-logs.js`** | **bktide cannot get logs** |
|
||||
| Get log metadata | ✅ `buildkite:get_logs_info` | ❌ | ❌ | |
|
||||
| List artifacts | ✅ `buildkite:list_artifacts` | ❌ | ❌ | |
|
||||
| Wait for build | ✅ `buildkite:wait_for_build` | ❌ | ✅ `wait-for-build.js` | MCP preferred |
|
||||
| Unblock jobs | ✅ `buildkite:unblock_job` | ❌ | ❌ | |
|
||||
| Real-time updates | ✅ | ❌ | ✅ | Via polling |
|
||||
| Human-readable output | ❌ (JSON) | ✅ | Varies | |
|
||||
| Works offline | ❌ | ❌ | ❌ | All need network |
|
||||
| Requires auth | ✅ (MCP config) | ✅ (BK_TOKEN) | ✅ (uses bktide) | |
|
||||
|
||||
## Detailed Tool Information
|
||||
|
||||
### MCP Tools (Primary)
|
||||
|
||||
**Access Method:** `mcp__MCPProxy__call_tool("buildkite:<tool>", {...})`
|
||||
|
||||
**Authentication:** Configured in MCP server settings (typically uses `BUILDKITE_API_TOKEN`)
|
||||
|
||||
**Pros:**
|
||||
|
||||
- Complete API coverage
|
||||
- Always available (no external dependencies)
|
||||
- Real-time data
|
||||
- Structured JSON responses
|
||||
|
||||
**Cons:**
|
||||
|
||||
- Verbose JSON output
|
||||
- Requires parsing for human reading
|
||||
|
||||
**Key Tools:**
|
||||
|
||||
#### `buildkite:get_build`
|
||||
|
||||
Get detailed build information including job states, timing, and metadata.
|
||||
|
||||
Parameters:
|
||||
|
||||
- `org_slug` (required): Organization slug
|
||||
- `pipeline_slug` (required): Pipeline slug
|
||||
- `build_number` (required): Build number
|
||||
- `detail_level` (optional): "summary" | "detailed" | "complete"
|
||||
- `job_state` (optional): Filter jobs by state ("failed", "passed", etc.)
|
||||
|
||||
Returns: Build object with jobs array, state, timing, author, etc.
|
||||
|
||||
#### `buildkite:get_logs`
|
||||
|
||||
**THE CRITICAL TOOL** - Retrieve actual log output from a job.
|
||||
|
||||
Parameters:
|
||||
|
||||
- `org_slug` (required): Organization slug
|
||||
- `pipeline_slug` (required): Pipeline slug
|
||||
- `build_number` (required): Build number
|
||||
- `job_id` (required): Job UUID (NOT step ID from URL)
|
||||
|
||||
Returns: Log text content
|
||||
|
||||
**Common Issues:**
|
||||
|
||||
- "job not found" → Using step ID instead of job UUID
|
||||
- Empty response → Job hasn't started or finished yet
|
||||
|
||||
#### `buildkite:wait_for_build`
|
||||
|
||||
Poll build until completion.
|
||||
|
||||
Parameters:
|
||||
|
||||
- `org_slug` (required): Organization slug
|
||||
- `pipeline_slug` (required): Pipeline slug
|
||||
- `build_number` (required): Build number
|
||||
- `timeout` (optional): Seconds until timeout (default: 1800)
|
||||
- `poll_interval` (optional): Seconds between checks (default: 30)
|
||||
|
||||
Returns: Final build state when complete or timeout
|
||||
|
||||
### bktide CLI (Secondary)
|
||||
|
||||
**Access Method:** `npx bktide <command>`
|
||||
|
||||
**Authentication:** `BK_TOKEN` environment variable or `~/.bktide/config`
|
||||
|
||||
**Pros:**
|
||||
|
||||
- Human-readable colored output
|
||||
- Intuitive command structure
|
||||
- Good for interactive terminal work
|
||||
|
||||
**Cons:**
|
||||
|
||||
- External npm dependency
|
||||
- **CANNOT retrieve job logs** (most critical limitation)
|
||||
- Limited compared to full API
|
||||
- Requires npx/node installed
|
||||
|
||||
**Key Commands:**
|
||||
|
||||
```bash
|
||||
npx bktide pipelines <org> # List pipelines
|
||||
npx bktide builds <org>/<pipeline> # List recent builds
|
||||
npx bktide build <org>/<pipeline>/<number> # Build details
|
||||
npx bktide build <org>/<pipeline>/<number> --jobs # Show job summary
|
||||
npx bktide build <org>/<pipeline>/<number> --failed # Show failed jobs only
|
||||
npx bktide annotations <org>/<pipeline>/<number> # Show annotations
|
||||
```
|
||||
|
||||
**Critical**: bktide has NO command for retrieving logs. The `build` command shows job states and names, but NOT log content.
|
||||
|
||||
### Bundled Scripts (Tertiary)
|
||||
|
||||
**Access Method:** `~/.claude/skills/buildkite-status/scripts/<script>.js`
|
||||
|
||||
**Authentication:** Use bktide internally (requires `BK_TOKEN`)
|
||||
|
||||
**Pros:**
|
||||
|
||||
- Purpose-built for specific workflows
|
||||
- Handle common use cases automatically
|
||||
- Provide structured output
|
||||
|
||||
**Cons:**
|
||||
|
||||
- Depend on bktide (external dependency)
|
||||
- Limited to specific use cases
|
||||
- May have version compatibility issues
|
||||
|
||||
**Available Scripts:**
|
||||
|
||||
#### `find-commit-builds.js`
|
||||
|
||||
Find builds matching a specific commit SHA.
|
||||
|
||||
Usage:
|
||||
|
||||
```bash
|
||||
~/.claude/skills/buildkite-status/scripts/find-commit-builds.js <org> <commit-sha>
|
||||
```
|
||||
|
||||
Returns: JSON array of matching builds
|
||||
|
||||
#### `wait-for-build.js`
|
||||
|
||||
Monitor build until completion (background-friendly).
|
||||
|
||||
Usage:
|
||||
|
||||
```bash
|
||||
~/.claude/skills/buildkite-status/scripts/wait-for-build.js <org> <pipeline> <build> [options]
|
||||
```
|
||||
|
||||
Options:
|
||||
|
||||
- `--timeout <seconds>`: Max wait time (default: 1800)
|
||||
- `--interval <seconds>`: Poll interval (default: 30)
|
||||
|
||||
Exit codes:
|
||||
|
||||
- 0: Build passed
|
||||
- 1: Build failed
|
||||
- 2: Build canceled
|
||||
- 3: Timeout
|
||||
|
||||
#### `get-build-logs.js` (NEW - to be implemented)
|
||||
|
||||
Retrieve logs for a failed job with automatic UUID resolution.
|
||||
|
||||
Usage:
|
||||
|
||||
```bash
|
||||
~/.claude/skills/buildkite-status/scripts/get-build-logs.js <org> <pipeline> <build> <job-label-or-uuid>
|
||||
```
|
||||
|
||||
Features:
|
||||
|
||||
- Accepts job label or UUID
|
||||
- Automatically resolves label → UUID
|
||||
- Handles step ID confusion
|
||||
- Formats output for readability
|
||||
|
||||
## Decision Matrix: Which Tool to Use
|
||||
|
||||
### Use MCP Tools When:
|
||||
|
||||
- Getting build details
|
||||
- **Retrieving job logs** (ONLY option with bktide)
|
||||
- Waiting for builds (preferred over script)
|
||||
- Unblocking jobs
|
||||
- Automating workflows
|
||||
- Need structured data
|
||||
|
||||
### Use bktide When:
|
||||
|
||||
- Interactive terminal work
|
||||
- Want human-readable summary
|
||||
- Listing pipelines/builds
|
||||
- Getting quick status overview
|
||||
- **NOT when you need logs** (it can't do this)
|
||||
|
||||
### Use Scripts When:
|
||||
|
||||
- Need specialized workflow (find commits)
|
||||
- Want background monitoring
|
||||
- MCP tools fail (fallback)
|
||||
- Automating repetitive tasks
|
||||
|
||||
## Common Mistakes
|
||||
|
||||
### ❌ Trying to get logs with bktide
|
||||
|
||||
**Don't**: `npx bktide build <org>/<pipeline>/<number> --logs`
|
||||
|
||||
**Why**: This flag doesn't exist. bktide cannot retrieve logs.
|
||||
|
||||
**Do**: Use `buildkite:get_logs` MCP tool
|
||||
|
||||
### ❌ Using step ID for log retrieval
|
||||
|
||||
**Don't**: Extract `sid=019a5f...` from URL and use directly
|
||||
|
||||
**Why**: Step IDs ≠ Job UUIDs. MCP tools need job UUIDs.
|
||||
|
||||
**Do**: Call `buildkite:get_build` to get job details, extract `uuid` field
|
||||
|
||||
### ❌ Abandoning MCP tools when script fails
|
||||
|
||||
**Don't**: "Script failed, I'll use GitHub instead"
|
||||
|
||||
**Why**: Scripts depend on bktide. MCP tools are independent.
|
||||
|
||||
**Do**: Use MCP tools directly when scripts fail
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Issue: "job not found" when calling get_logs
|
||||
|
||||
**Diagnosis**: Using step ID instead of job UUID
|
||||
|
||||
**Solution**:
|
||||
|
||||
1. Call `buildkite:get_build` with `detail_level: "detailed"`
|
||||
2. Find job by `label` field
|
||||
3. Extract `uuid` field
|
||||
4. Use that UUID in `get_logs` call
|
||||
|
||||
### Issue: bktide command not found
|
||||
|
||||
**Diagnosis**: npm/npx not installed or not in PATH
|
||||
|
||||
**Solution**:
|
||||
|
||||
1. Use MCP tools instead (preferred)
|
||||
2. Or install: `npm install -g @anthropic/bktide`
|
||||
|
||||
### Issue: Empty logs returned
|
||||
|
||||
**Diagnosis**: Job hasn't completed or logs not available yet
|
||||
|
||||
**Solution**:
|
||||
|
||||
1. Check job `state` - should be terminal (passed/failed/canceled)
|
||||
2. Wait for job to finish
|
||||
3. Check job `started_at` and `finished_at` timestamps
|
||||
|
||||
## See Also
|
||||
|
||||
- [SKILL.md](../SKILL.md) - Main skill documentation
|
||||
- [troubleshooting.md](troubleshooting.md) - Common errors and solutions
|
||||
- [url-parsing.md](url-parsing.md) - Understanding Buildkite URLs
|
||||
Reference in New Issue
Block a user