---
name: mosaic-woodpecker
description: Manage Woodpecker CI pipelines for Mosaic Stack projects. Use when checking pipeline status, triggering pipelines, waiting for CI to complete, or debugging build failures. Wraps scripts in ~/.config/mosaic/tools/woodpecker/. CI URL: https://ci.mosaicstack.dev.
---

# mosaic-woodpecker

Woodpecker CI management via Mosaic wrapper scripts.

## Setup

```bash
source ~/.config/mosaic/tools/_lib/credentials.sh
load_credentials woodpecker
# Exports: WOODPECKER_URL, WOODPECKER_TOKEN
```

For a specific instance (e.g. `usc`):
```bash
load_credentials woodpecker-usc
```

## Scripts

All scripts in `~/.config/mosaic/tools/woodpecker/`.

| Script | Purpose | Key flags |
|---|---|---|
| `pipeline-status.sh` | Check pipeline status | `[-r owner/repo] [-n number] [-f json\|table]` |
| `pipeline-list.sh` | List recent pipelines | `[-r owner/repo] [-l limit]` |
| `pipeline-trigger.sh` | Trigger a pipeline | `[-r owner/repo] [-b branch]` |

CI queue management is in `~/.config/mosaic/tools/git/`:

| Script | Purpose | Key flags |
|---|---|---|
| `ci-queue-wait.sh` | Wait for CI queue slot | `[-t timeout_sec] [-B branch] [--purpose merge]` |
| `pr-ci-wait.sh` | Wait for PR CI to pass | `-n <pr#> [-t timeout]` |

## Common Workflows

**Check latest pipeline on current repo:**
```bash
cd ~/src/<repo>
source ~/.config/mosaic/tools/_lib/credentials.sh && load_credentials woodpecker
~/.config/mosaic/tools/woodpecker/pipeline-status.sh
```

**Check specific pipeline number:**
```bash
~/.config/mosaic/tools/woodpecker/pipeline-status.sh -n 42
```

**Wait for CI before merging:**
```bash
cd ~/src/<repo>
~/.config/mosaic/tools/git/pr-ci-wait.sh -n <pr#>
```

**Trigger a pipeline on a branch:**
```bash
~/.config/mosaic/tools/woodpecker/pipeline-trigger.sh -r mosaic/mosaic-stack -b main
```

## Notes

- CI URL: `https://ci.mosaicstack.dev`
- Credentials: `load_credentials woodpecker` (from `~/src/jarvis-brain/credentials.json`)
- `ci-queue-wait.sh` is automatically called by `pr-merge.sh` unless `--skip-queue-guard` is passed
- Pipeline output shows step-level status: OK / FAIL / RUN / SKIP / WAIT