quickseal 0.1.4

# CI/CD Setup and Usage Guide

This document explains the CI/CD infrastructure for the Seal CLI project.

## Overview

The project uses GitHub Actions for continuous integration and delivery with comprehensive automation for testing, security, and releases.

## Workflows

### 1. CI Workflow (`.github/workflows/ci.yml`)

**Triggers:** Every push and pull request

**Jobs:**
- **Format Check** - Validates code formatting with `cargo fmt`
- **Clippy Lints** - Runs Clippy static analysis with warnings as errors
- **Test Suite** - Runs unit and doc tests on 3 platforms:
  - Ubuntu Latest (Linux)
  - macOS Latest
  - Windows Latest
- **Security Audit** - Checks for known security vulnerabilities with `cargo audit`
- **Documentation** - Builds docs and checks for warnings
- **Build Check** - Compiles release binaries for all platforms and uploads artifacts

**Performance Features:**
- Cargo caching for faster builds (registry, index, build artifacts)
- Parallel job execution across platforms
- Typical run time: 3-5 minutes

**Status:** ✅ All checks passing

### 2. Release Workflow (`.github/workflows/release.yml`)

**Triggers:** Version tags (e.g., `v0.1.0`, `v1.2.3`)

**Jobs:**
- Builds release binaries for 5 platforms:
  - Linux x86_64
  - Linux ARM64 (aarch64)
  - macOS x86_64
  - macOS ARM64 (Apple Silicon)
  - Windows x86_64
- Creates GitHub Release with binaries attached
- Publishes to crates.io automatically

**Required Secrets:**
- `CARGO_REGISTRY_TOKEN` - For crates.io publishing (✅ configured)

**Usage:**
```bash
# Create and push a version tag to trigger release
git tag v0.1.0
git push origin v0.1.0
```

### 3. Security Workflow (`.github/workflows/security.yml`)

**Triggers:** Daily at 00:00 UTC + manual dispatch

**Jobs:**
- **Cargo Audit** - Checks for vulnerable dependencies
- **Dependency Check** - Validates dependency tree health
- **License Compliance** - Ensures all dependencies have acceptable licenses
- **SAST Scan** - Static application security testing with Clippy security lints

**Failure Handling:**
- Creates GitHub issues automatically for security failures
- Continues on error to complete all checks

### 4. Coverage Workflow (`.github/workflows/coverage.yml`)

**Triggers:** Pull requests to main

**Jobs:**
- Generates code coverage report with `cargo-llvm-cov`
- Uploads to Codecov for tracking
- Enforces 70% minimum coverage threshold

**Required Secrets:**
- `CODECOV_TOKEN` - For coverage uploads (✅ configured)

## Automated Dependency Updates

**Dependabot** (`.github/dependabot.yml`)

- Checks for Cargo dependency updates weekly
- Checks for GitHub Actions updates weekly
- Groups minor and patch updates together
- Automatically opens PRs with update recommendations

## GitHub Secrets Configuration

The following secrets are configured in the repository:

| Secret Name | Purpose | Status |
|------------|---------|--------|
| `CARGO_REGISTRY_TOKEN` | Publishing to crates.io | ✅ Configured |
| `CODECOV_TOKEN` | Code coverage uploads | ✅ Configured |

**How secrets were added:**
```bash
# Using GitHub CLI (gh)
gh secret set CARGO_REGISTRY_TOKEN --body "your-token"
gh secret set CODECOV_TOKEN --body "your-token"
```

## Quality Gates

Before code can be merged, all of these must pass:

1. ✅ Code formatting (`cargo fmt`)
2. ✅ Clippy lints (no warnings allowed)
3. ✅ Unit tests (all platforms)
4. ✅ Doc tests
5. ✅ Security audit
6. ✅ Documentation builds
7. ✅ Release builds succeed

## Pull Request Template

The PR template (`.github/PULL_REQUEST_TEMPLATE.md`) includes:
- Summary section
- Test plan checklist
- Constitutional compliance checklist
- Breaking changes documentation

## Issue Templates

Two issue templates are available:

1. **Bug Report** - Structured bug reporting with environment details
2. **Feature Request** - Feature proposal with use case and acceptance criteria

## Running CI Checks Locally

Before pushing, you can run the same checks locally:

```bash
# Format check
cargo fmt --check

# Clippy
cargo clippy --all-targets --all-features -- -D warnings

# Tests
cargo test --all-features

# Documentation
cargo doc --no-deps --all-features

# Security audit (requires cargo-audit)
cargo install cargo-audit
cargo audit

# Build release binary
cargo build --release
```

## Troubleshooting

### CI Failures

**Format Check Failed:**
```bash
# Auto-fix formatting
cargo fmt
git add .
git commit -m "fix: Apply cargo fmt formatting"
```

**Clippy Failed:**
```bash
# Run clippy locally to see issues
cargo clippy --all-targets --all-features -- -D warnings

# Fix issues and commit
git add .
git commit -m "fix: Address clippy warnings"
```

**Tests Failed:**
```bash
# Run tests with verbose output
cargo test --all-features -- --nocapture

# Run specific test
cargo test test_name -- --nocapture
```

### Release Issues

**crates.io publish failed:**
- Verify `CARGO_REGISTRY_TOKEN` is valid
- Check that version in `Cargo.toml` is bumped
- Ensure version doesn't already exist on crates.io

**GitHub Release failed:**
- Ensure tag follows semver format (`vX.Y.Z`)
- Check that all build jobs completed successfully

## Next Steps

Possible future enhancements:

1. **Performance Benchmarking** - Add criterion benchmarks to CI
2. **Integration Tests** - Add end-to-end tests with real kubeseal
3. **Mutation Testing** - Add cargo-mutants for test quality
4. **Fuzzing** - Add cargo-fuzz for security-critical code
5. **Cross-compilation** - Add more platform targets (FreeBSD, ARM variants)

## Monitoring

**GitHub Actions Status:**
```bash
# Check recent workflow runs
gh run list --limit 10

# Watch a specific run
gh run watch <run-id>

# View run logs
gh run view <run-id> --log
```

**Codecov Dashboard:**
Visit `https://codecov.io/gh/haimari/seal` to view coverage trends

## Resources

- [GitHub Actions Documentation](https://docs.github.com/en/actions)
- [cargo-audit](https://github.com/rustsec/rustsec/tree/main/cargo-audit)
- [cargo-llvm-cov](https://github.com/taiki-e/cargo-llvm-cov)
- [Codecov](https://docs.codecov.com/)