292 lines
9.0 KiB
Markdown
292 lines
9.0 KiB
Markdown
# 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
|