circleci

Files (1)

• SKILL.md

SKILL.md (first lines)

# CircleCI Build Debugging

Use this skill when debugging CI/CD failures, fetching test results, downloading build artifacts, or investigating failed jobs on CircleCI. This covers both CircleCI Server (on-prem) and CircleCI Cloud instances.

## Environment

| Setting | Value |
|---------|-------|
| CircleCI Server Base URL | `https://gcp-circleci.build.corp.creditkarma.com` |
| CircleCI App URL | `https://app.gcp-circleci.build.corp.creditkarma.com` |
| API Base | `https://gcp-circleci.build.corp.creditkarma.com/api/v2` |
| API v1.1 Base | `https://gcp-circleci.build.corp.creditkarma.com/api/v1.1` |
| Token Settings Page | `https://app.gcp-circleci.build.corp.creditkarma.com/settings/user/tokens` |
| VCS Slug | `gh` (GitHub) |
| Default Org | `ck-private` |
| Auth Header | `Circle-Token: <token>` |
| Token Location | `~/.circleci/token` (plain text file containing just the token) |

## Authentication

A CircleCI Personal API Token is required. The token should be stored in `~/.circleci/token`.

To create a token:
1. Open `https://app.gcp-circleci.build.corp.creditkarma.com/settings/user/tokens` in your browser (VPN required)
2. Click **Create New Token**, give it a name (e.g., `opencode`)
3. Copy the token (it is only shown once) and save it:

```bash
mkdir -p ~/.circleci && echo "YOUR_TOKEN" > ~/.circleci/token && chmod 600 ~/.circleci/token
```

```bash
# Verify token works
CIRCLE_TOKEN=$(cat ~/.circleci/token)
curl -s -H "Circle-Token: $CIRCLE_TOKEN" \
  "https://gcp-circleci.build.corp.creditkarma.com/api/v2/me" | jq .
```

If the token file does not exist, inform the user they need to create one and provide the instructions above.

## URL Parsing

CircleCI build URLs follow this pattern:
```
https://<host>/gh/<org>/<repo>/<build_number>
```

Example: `https://gcp-circleci.build.corp.creditkarma.com/gh/ck-private/daf_dataflow-templates/2247`

Extract from this:
- **host**: `gcp-circleci.build.corp.creditkarma.com`
- **project-slug**: `gh/ck-private/daf_dataflow-templates`
- **build_number** (also called job number): `2247`

For CircleCI Cloud URLs, the host is `app.circleci.com` and the API base is `https://circleci.com/api/v2`.

## Key API Endpoints

All examples use `$BASE=https://gcp-circleci.build.corp.creditkarma.com/api` and `$CIRCLE_TOKEN=$(cat ~/.circleci/token)`.

### 1. Get Job Details (by job number)

Returns job status, duration, executor, and related pipeline/workflow info.

```bash
# API v1.1 - Get build details by build number (most useful for single build URLs)
curl -s -H "Circle-Token: $CIRCLE_TOKEN" \
  "$BASE/v1.1/project/gh/<org>/<repo>/<build_number>" | jq .
```

The v1.1 endpoint returns rich data including:
- `status`: "success", "failed", "running", etc.
- `steps[].actions[]`: Each step with its name, status, output URL, and exit code
- `build_url`: Link back to the UI
- `branch`, `vcs_revision`: Git context
- `workflows`: Workflow name and job name

### 2. Get Test Metadata (failed tests)

Returns structured test results (requires `store_test_results` in the CircleCI config).

```bash
# API v2 - Get test metadata for a job (requires job number from project slug)
# First get the job number from the pipeline
curl -s -H "Circle-Token: $CIRCLE_TOKEN" \
  "$BASE/v2/project/gh/<org>/<repo>/<build_number>/tests" | jq .
```

Response contains:
- `items[].classname`: Test class
- `items[].name`: Test name
- `items[].result`: "success" or "failure"
- `items[].message`: Failure message/stack trace
- `items[].run_time`: Duration in seconds
- `items[].source`: Test framework

To get only failures:
```bash
curl -s -H "Circle-Token: $CIRCLE_TOKEN" \
  "$BASE/v2/project/gh/<org>/<repo>/<build_number>/tests" | \
  jq '.items[] | select(.result == "failure")'
```

### 3. Get Job Artifacts

Returns downloadable artifacts (logs, reports, binaries).

```bash
# API v2
curl -s -H "Circle-Token: $CIRCLE_TOKEN" \
  "$BASE/v2/project/gh/<org>/<repo>/<build_number>/artifacts" | jq .
```

Response contains:
- `items[].path`: Artifact file path
- `items[].url`: Direct download URL
- `items[].node_index`: For parallel jobs

To download an artifact:

From djmittens/neo-mittens, MIT.

More from djmittens/neo-mittens