TypeDialog/docs/ci/README.md

# CI/CD Pipelines

TypeDialog uses **dual CI/CD setup** to support both GitHub and Gitea/Forgejo platforms.

## Quick Reference

| Platform           | Files                        | Documentation                |
| ------------------ | ---------------------------- | ---------------------------- |
| **GitHub Actions** | `.github/workflows/*.yml`    | Auto-configured              |
| **Woodpecker CI**  | `.woodpecker/*.yml`          | See `.woodpecker/README.md`  |

## Platform Comparison

| Feature         | GitHub Actions             | Woodpecker Basic           | Woodpecker Advanced/Docker |
| --------------- | -------------------------- | -------------------------- | -------------------------- |
| **Multi-OS** | ✅ Linux, macOS, Windows | ❌ Linux only | ✅ 5 targets* |
| **Linting** | ✅ 5 languages (parallel) | ✅ 5 languages (parallel) | ✅ 5 languages (parallel) |
| **Testing** | ✅ Matrix (3 OS) | ✅ Linux | ✅ Multi-OS** |
| **Coverage** | ✅ Codecov integration | ❌ | ✅ SonarQube** |
| **Security** | ✅ cargo-audit | ✅ cargo-audit | ✅ cargo-audit |
| **Compliance** | ✅ cargo-deny | ✅ cargo-deny | ✅ cargo-deny |
| **Benchmarks** | ✅ On PRs | ❌ | ✅ Gitea API** |
| **SBOM** | ✅ Auto-upload | ⚠️  Manual upload | ✅ Auto-upload |
| **Release** | ✅ 6 targets + crates.io | ❌ 1 target | ✅ 5 targets + crates.io |
| **Gitea API** | N/A | ❌ | ✅ Auto-create releases |

\* Advanced: cross-compilation, Docker: .woodpecker/Dockerfile.cross
\*\* Advanced pipelines only (ci-advanced.yml, release-advanced.yml, release-docker.yml)

## CI Pipeline (Both Platforms)

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

**Stages**:

1. **Linting** (parallel):
   - Rust (clippy)
   - Bash (shellcheck)
   - Nickel
   - Nushell
   - Markdown
2. **Testing**: `just ci::test-all`
3. **Building**: `just ci::build-release`
4. **Security**: `cargo audit`
5. **Compliance**: `cargo deny check licenses`

**Duration**:

- GitHub Actions: ~20-25 min
- Woodpecker CI: ~15-20 min (with custom image), ~25-30 min (without)

## Release Pipeline (Both Platforms)

**Triggers**: Git tags `v*` (e.g., `v0.1.0`)

**GitHub Actions**: 6 targets, auto-upload, auto-publish to crates.io

**Woodpecker CI**: 3 pipeline options

- **Basic** (`release.yml`) - Linux x86_64 only, manual upload
- **Advanced** (`release-advanced.yml`) - 5 targets, Gitea API auto-upload
- **Docker-based** (`release-docker.yml`) - 5 targets, uses .woodpecker/Dockerfile.cross, Gitea API

**Artifacts**:

- Release binaries (GitHub: 6 targets, Woodpecker: 1-5 depending on pipeline)
- SHA256 checksums
- SBOM (SPDX + CycloneDX formats)
- BUILD_INFO.json manifest (Woodpecker Docker-based only)
- Auto-publish to crates.io (optional on both platforms)

## Local Testing

Test before pushing:

```bash
just ci::full          # Complete pipeline
just ci::test-all      # Tests only
just ci::audit         # Security audit
just ci::deny          # License check
```

## Setup

### GitHub Actions (Auto-configured)

Secrets required:

- `CODECOV_TOKEN` - For coverage reports
- `CARGO_REGISTRY_TOKEN` - For crates.io publishing

### Woodpecker CI (Manual)

See [`.woodpecker/README.md`](../../.woodpecker/README.md) for:

- Activation steps
- Custom Docker image (optional, faster CI)
- Secrets configuration

## Creating a Release

```bash
# 1. Update version in Cargo.toml files
# 2. Commit changes
git commit -am "chore: bump version to 0.1.0"

# 3. Create and push tag
git tag v0.1.0
git push origin v0.1.0

# 4. CI systems will:
#    GitHub Actions:
#      - Build 6 platform binaries
#      - Generate SBOMs
#      - Create GitHub Release with auto-upload
#      - Publish to crates.io
#
#    Woodpecker CI:
#      - Basic: Build Linux x86_64 binary, generate SBOM (manual upload)
#      - Advanced: Build 5 platform binaries, auto-create Gitea release, upload artifacts
#      - Docker-based: Build 5 platforms via .woodpecker/Dockerfile.cross, auto-create Gitea release
#      - Optional: Publish to crates.io (if CARGO_TOKEN configured)
```

**Woodpecker Pipeline Selection**:

Choose which release pipeline to use by renaming in `.woodpecker/`:

- Keep only one `release.yml` active
- Rename others to `.release-*.yml.disabled`

Example (use Docker-based):

```bash
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
```

## Troubleshooting

### Tests Failing

Some tests require `ANTHROPIC_API_KEY` and are marked `#[ignore]`:

```bash
# Run locally with API key
export ANTHROPIC_API_KEY=sk-xxx
cargo test -- --ignored
```

### CI Caching Issues

**GitHub**: Clear caches via Actions UI

**Woodpecker**: Server-side cache configuration (ask admin)

### Security Audit Warnings

See `.cargo/audit.toml` for ignored advisories (unmaintained deps with no alternatives).

## More Information

- **Just commands**: See `justfiles/*.just`
- **Woodpecker setup**: See `.woodpecker/README.md`
- **Project structure**: See `README.md`