TypeDialog/.woodpecker/README.md

# Woodpecker CI Configuration

Pipelines for Gitea/Forgejo + Woodpecker CI.

## Files

### CI Pipeline
- **`ci.yml`** - Main CI pipeline (push, pull requests)
- **`ci-advanced.yml`** - Advanced CI with multi-OS matrix, coverage, benchmarks

### Release Pipelines
- **`release.yml`** - Basic release (Linux only, no Docker)
- **`release-advanced.yml`** - Advanced release (multi-OS, Gitea API, auto-upload)
- **`release-docker.yml`** - Docker-based release (uses .woodpecker/Dockerfile.cross)

### Docker Images

**CI Images** (pre-install tools, speed up CI ~5min):
- **`Dockerfile`** - Original (2.47GB, ❌ too large)
- **`Dockerfile.optimized`** - Multi-stage build (~800MB)
- **`Dockerfile.alpine`** - Alpine-based (~400MB, smallest)
- **`Dockerfile.prebuilt`** - Pre-compiled binaries (1.68GB, 3min build, **recommended**)
- **`Dockerfile.minimal`** - Prebuilt without nu (~1.6GB, 2min build, fastest)

**Build Images**:
- **`Dockerfile.cross`** - Cross-compilation image for multi-platform builds

## Setup

### 1. Activate Woodpecker CI

Enable Woodpecker CI in your Gitea/Forgejo repository settings.

### 2. (Optional) Build Custom Image

Speeds up CI by pre-installing tools (~5 min faster per run).

**Five Dockerfile options available**:

| Dockerfile | Size | Build Time | Tools | Use Case |
|------------|------|------------|-------|----------|
| `Dockerfile` | **2.47GB** | ~20 min | All + cargo cache | ❌ Too large (original) |
| `Dockerfile.optimized` | **~800MB** | ~15 min | All (multi-stage) | ✅ Multi-stage, Debian-based |
| `Dockerfile.alpine` | **~400MB** | ~12 min | All (Alpine) | ✅ Alpine-based, smallest |
| `Dockerfile.prebuilt` | **1.68GB** | **~3 min** | All (cargo-binstall) | ✅ Pre-compiled binaries, **fastest** |
| `Dockerfile.minimal` | **~1.6GB** | **~2 min** | All except nu | ✅ Fastest + smallest (no nushell lint) |

**Recommended: Use `Dockerfile.prebuilt`** (fastest builds, all tools)

**For minimal size**: Use `Dockerfile.minimal` if you can skip nushell linting (saves 46MB + 1min build)

```bash
# Build optimized image (choose one)
docker build -t your-registry/typedialog-ci:latest -f .woodpecker/Dockerfile.prebuilt .

# Or for smallest size (Alpine)
docker build -t your-registry/typedialog-ci:alpine -f .woodpecker/Dockerfile.alpine .

# Push to your registry
docker push your-registry/typedialog-ci:latest

# Update .woodpecker/ci.yml and ci-advanced.yml
# Change: image: rust:latest
# To: image: your-registry/typedialog-ci:latest
```

**Size comparison breakdown**:
```
Original (Dockerfile):
  Base Debian + buildtools:  1.6GB
  Rust toolchain:            538MB
  cargo install (5 tools):   823MB (includes cargo cache)
  --------------------------------
  TOTAL:                    2.47GB

Optimized (Dockerfile.prebuilt):
  Base Rust slim:            400MB
  Runtime deps:               60MB
  Binaries only:             140MB (no cargo cache)
  --------------------------------
  TOTAL:                    ~600MB
```

### 3. Secrets Configuration

Configure these secrets in Gitea/Forgejo repository settings:

- `GITEA_TOKEN` - Gitea/Forgejo API token (for auto-creating releases)
- `CARGO_TOKEN` - crates.io token (optional, for publishing to crates.io)
- `SONAR_TOKEN` - SonarQube token (optional, for ci-advanced.yml coverage)

**To create a Gitea token**:
1. Go to Settings → Applications → Manage Access Tokens
2. Create token with scopes: `write:repository`, `write:issue`
3. Add as secret `GITEA_TOKEN` in repository settings

### 4. Docker Access (for release-docker.yml)

The `release-docker.yml` pipeline requires access to Docker socket. Configure in Woodpecker server:

**Option A: Privileged mode** (simpler, less secure):
```yaml
# In Woodpecker server config
WOODPECKER_BACKEND_DOCKER_ENABLE_PRIVILEGED: true
```

**Option B: Volume mount** (recommended):
Already configured in pipeline via:
```yaml
volumes:
  - /var/run/docker.sock:/var/run/docker.sock
```

Ensure Woodpecker agent has permission to access Docker socket.

## Pipelines

### CI Pipeline (`ci.yml`)

**Triggers**: Push to `main`/`develop`, Pull Requests

**Jobs**:
1. Lint (Rust, Bash, Nickel, Nushell, Markdown) - Parallel
2. Test (all features)
3. Build (release)
4. Security audit
5. License compliance check

**Duration**: ~15-20 minutes (without custom image), ~10-15 minutes (with custom image)

### Release Pipelines

All release pipelines trigger on Git tags `v*` (e.g., `v0.1.0`).

#### Option 1: Basic Release (`release.yml`)

**Use case**: Simple Linux-only releases, no Docker required

**Platforms**: x86_64-unknown-linux-gnu only

**Artifacts**:
- `typedialog-${VERSION}-x86_64-linux.tar.gz`
- `typedialog-${VERSION}-x86_64-linux.tar.gz.sha256`
- `sbom-spdx.json`, `sbom-cyclonedx.json`

**Duration**: ~20-25 minutes

#### Option 2: Advanced Release (`release-advanced.yml`)

**Use case**: Multi-platform builds with auto-upload to Gitea

**Platforms**: 5 targets (Linux x86_64/aarch64, macOS x86_64/aarch64, Windows x86_64)

**Features**:
- Auto-creates Gitea release via API
- Matrix builds with `cross` tool
- Auto-uploads all artifacts to release
- Optional crates.io publishing

**Requirements**: `GITEA_TOKEN` secret

**Duration**: ~30-40 minutes (parallel builds)

#### Option 3: Docker-based Release (`release-docker.yml`)

**Use case**: Consistent builds using existing .woodpecker/Dockerfile.cross

**Platforms**: 5 targets (same as advanced)

**Features**:
- Uses project's `.woodpecker/Dockerfile.cross` for reproducible builds
- Includes BUILD_INFO.json manifest
- Auto-creates Gitea release and uploads artifacts
- Optional crates.io publishing

**Requirements**:
- `GITEA_TOKEN` secret
- Docker socket access (see Setup section)

**Duration**: ~35-45 minutes (includes Docker builds)

**Comparison**:

| Feature | Basic | Advanced | Docker-based |
|---------|-------|----------|--------------|
| Platforms | 1 (Linux x86_64) | 5 | 5 |
| Gitea API | ❌ Manual | ✅ Auto | ✅ Auto |
| Docker required | ❌ | ❌ | ✅ |
| Build method | cargo | cross CLI | .woodpecker/Dockerfile.cross |
| Consistency | Standard | Standard | High (containerized) |
| Manifest | ❌ | ❌ | ✅ BUILD_INFO.json |

## Differences from GitHub Actions

| Feature | GitHub Actions | Woodpecker CI |
|---------|---------------|---------------|
| Matrix builds | ✅ 3 OS | ❌ Linux only* |
| Coverage | ✅ Codecov | ❌ Not configured |
| Benchmarks | ✅ On PRs | ❌ Not configured |
| Caching | ✅ Built-in | ⚠️  Server-side** |
| SBOM | ✅ Auto-upload | ⚠️  Manual*** |

\* Multi-OS builds require multiple Woodpecker agents  
\*\* Configure in Woodpecker server settings  
\*\*\* Manual upload to Gitea/Forgejo releases

## Triggering Pipelines

```bash
# CI pipeline (automatic on push/PR)
git push origin main

# Release pipeline (manual tag)
git tag v0.1.0
git push origin v0.1.0
```

**Selecting Release Pipeline**:

By default, all three release pipelines will trigger on tags. To use only one:

1. **Rename the pipeline you want to use** to `release.yml`
2. **Rename others** to `.release-*.yml.disabled` (Woodpecker ignores these)

Example:
```bash
# Use Docker-based release only
mv .woodpecker/release.yml .woodpecker/.release-basic.yml.disabled
mv .woodpecker/release-advanced.yml .woodpecker/.release-advanced.yml.disabled
mv .woodpecker/release-docker.yml .woodpecker/release.yml
```

Or configure in Woodpecker UI to enable/disable specific pipelines.

## Viewing Results

- **Gitea/Forgejo**: Repository → Actions → Pipeline runs
- **Woodpecker UI**: https://your-woodpecker.instance/repos/{user}/{repo}