---
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` (framework credentials store)
- `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
