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:

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 for:

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

Creating a Release

# 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):

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]:

# 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