horus/.gitea/workflows/README.md

# Gitea Actions Workflows Documentation

This directory contains the CI/CD workflows for the Horus project using Gitea Actions.

## Overview

The Horus project uses two main workflows:

1. **[ci.yml](./ci.yml)** - Continuous Integration workflow
2. **[release.yml](./release.yml)** - Release automation workflow

## Workflow Files

### ci.yml - Continuous Integration

**Purpose**: Automatically build, test, and validate code quality on every push and pull request.

**Triggers**:
- Push to any branch
- Pull request events (opened, synchronized, reopened)

**What it does**:
1. Sets up Rust toolchain
2. Caches dependencies for faster builds
3. Runs code quality checks (check, test, clippy, fmt)
4. Builds all 7 binaries in release mode
5. Uploads binaries as artifacts

**Duration**: ~5-15 minutes (first run), ~2-5 minutes (cached runs)

**Artifacts**: Binaries are stored for 7 days and can be downloaded from the Actions tab

---

### release.yml - Release Automation

**Purpose**: Automatically create GitHub-style releases with downloadable binaries when version tags are pushed.

**Triggers**:
- Tags matching `v*.*.*` pattern (e.g., `v1.0.0`, `v2.1.3`)

**What it does**:
1. Builds optimized release binaries
2. Strips debug symbols to reduce size
3. Packages each binary as a tarball
4. Generates SHA256 checksums
5. Creates a Gitea release with all artifacts attached

**Duration**: ~5-10 minutes

**Artifacts**: Permanently attached to the release

---

## Binaries Built

Both workflows build the following 7 binaries:

| Binary Name | Description |
|-------------|-------------|
| `supervisor` | Hero Supervisor service |
| `coordinator` | Hero Coordinator service |
| `horus` | Horus main binary |
| `osiris` | Osiris server |
| `herorunner` | Hero runner |
| `runner_osiris` | Osiris runner |
| `runner_sal` | SAL runner |

---

## Usage Guide

### Testing Code Changes

Every time you push code or create a pull request, the CI workflow automatically runs:

```bash
# Make your changes
git add .
git commit -m "Your changes"
git push origin your-branch

# Or create a pull request
# The CI workflow will run automatically
```

**Check Results**:
1. Go to your Gitea repository
2. Click on the **Actions** tab
3. Find your workflow run
4. Click to see detailed logs

---

### Creating a Release

To create a new release with binaries:

```bash
# 1. Ensure your code is ready for release
# 2. Create a version tag (use semantic versioning)
git tag v1.0.0

# 3. Push the tag
git push origin v1.0.0

# 4. The release workflow will automatically:
#    - Build all binaries
#    - Create a release
#    - Attach binaries and checksums
```

**View Release**:
1. Go to your Gitea repository
2. Click on the **Releases** tab
3. Your new release will be listed with downloadable artifacts

---

### Downloading Release Binaries

Users can download binaries from releases:

```bash
# Download a specific binary
wget https://git.ourworld.tf/peternashaat/horus/releases/download/v1.0.0/supervisor-v1.0.0-linux-x86_64.tar.gz

# Extract
tar -xzf supervisor-v1.0.0-linux-x86_64.tar.gz

# Make executable
chmod +x supervisor

# Optionally move to system path
sudo mv supervisor /usr/local/bin/

# Verify it works
supervisor --help
```

**Verify Integrity**:
```bash
# Download checksums
wget https://git.ourworld.tf/peternashaat/horus/releases/download/v1.0.0/checksums.txt

# Verify a binary
sha256sum -c checksums.txt
```

---

## Workflow Requirements

### Runner Configuration

Your Gitea Actions runner must be configured with these labels:
- `ubuntu-latest` (recommended)
- `ubuntu-22.04` (alternative)
- `ubuntu-20.04` (alternative)

### Permissions

The workflows require:
- Read access to repository code
- Write access to create releases (for release.yml)
- Access to `GITHUB_TOKEN` secret (automatically provided by Gitea)

### Dependencies

The workflows automatically install:
- Rust stable toolchain
- rustfmt (code formatter)
- clippy (linter)

No manual setup required!

---

## Caching Strategy

The CI workflow uses three levels of caching to speed up builds:

1. **Cargo Registry Cache** - Downloaded crate metadata
2. **Cargo Index Cache** - Git index of crates.io
3. **Build Cache** - Compiled dependencies

**Benefits**:
- First build: ~10-15 minutes
- Cached builds: ~2-5 minutes
- Saves bandwidth and runner resources

---

## Troubleshooting

### CI Workflow Fails

**Check these common issues**:

1. **Compilation Errors**
   - Review the "Check code" step logs
   - Fix Rust compilation errors locally first

2. **Test Failures**
   - Review the "Run tests" step logs
   - Run `cargo test --workspace` locally to reproduce

3. **Clippy Warnings**
   - Review the "Run clippy" step logs
   - Fix with: `cargo clippy --workspace --fix`

4. **Formatting Issues**
   - Review the "Check formatting" step logs
   - Fix with: `cargo fmt --all`

5. **Runner Offline**
   - Check if your Gitea Actions runner is running
   - Verify runner labels match workflow requirements

### Release Workflow Fails

**Check these common issues**:

1. **Tag Format**
   - Ensure tag matches `v*.*.*` pattern
   - Examples: `v1.0.0`, `v2.1.3`, `v0.1.0-beta`

2. **Binary Not Found**
   - Check if all binaries built successfully
   - Review the "Build release binaries" step logs

3. **Permission Denied**
   - Ensure runner has write access to create releases
   - Check repository settings

4. **Release Already Exists**
   - Delete the existing release first
   - Or use a different version tag

---

## Best Practices

### Version Tagging

Use [Semantic Versioning](https://semver.org/):
- `v1.0.0` - Major release (breaking changes)
- `v1.1.0` - Minor release (new features)
- `v1.0.1` - Patch release (bug fixes)
- `v1.0.0-beta.1` - Pre-release

### Commit Messages

Write clear commit messages for better release notes:
```bash
git commit -m "feat: Add new authentication system"
git commit -m "fix: Resolve memory leak in supervisor"
git commit -m "docs: Update installation guide"
```

### Testing Before Release

Always test before creating a release:
```bash
# Run all checks locally
cargo check --workspace
cargo test --workspace
cargo clippy --workspace -- -D warnings
cargo fmt --all -- --check

# Build release binaries locally
cargo build --workspace --release

# Test the binaries
./target/release/supervisor --help
```

---

## Workflow Customization

### Changing Rust Version

Edit the toolchain in both workflows:
```yaml
- name: Setup Rust toolchain
  uses: actions-rust-lang/setup-rust-toolchain@v1
  with:
    toolchain: 1.75.0  # Specify exact version
```

### Adding More Binaries

If you add new binaries to the workspace:

1. Update `ci.yml` - Add to the upload artifacts step
2. Update `release.yml` - Add to strip and package steps
3. Update this README

### Changing Artifact Retention

In `ci.yml`, modify the retention period:
```yaml
retention-days: 30  # Keep for 30 days instead of 7
```

### Adding Build Matrix

To build for multiple platforms, add a matrix strategy:
```yaml
jobs:
  build:
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
    runs-on: ${{ matrix.os }}
```

---

## Monitoring

### View Workflow Status

**In Gitea UI**:
1. Repository → Actions tab
2. See all workflow runs
3. Click any run for detailed logs

**Via Git**:
```bash
# List recent tags
git tag -l

# Show tag details
git show v1.0.0
```

### Workflow Badges

Add status badges to your README:
```markdown
![CI Status](https://git.ourworld.tf/peternashaat/horus/actions/workflows/ci.yml/badge.svg)
```

---

## Security Considerations

### Secrets

The workflows use `GITHUB_TOKEN` which is automatically provided by Gitea. This token:
- Has repository-scoped permissions
- Expires after the workflow run
- Cannot be accessed by pull requests from forks (for security)

### Binary Verification

Always verify downloaded binaries:
```bash
# Check SHA256 hash
sha256sum binary-name
# Compare with checksums.txt
```

### Supply Chain Security

The workflows:
- Use pinned action versions (`@v4`, `@v1`)
- Build from source (no pre-built binaries)
- Generate checksums for verification

---

## Additional Resources

- [Gitea Actions Documentation](https://docs.gitea.com/usage/actions/overview)
- [GitHub Actions Syntax](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions) (Gitea is compatible)
- [Rust CI Best Practices](https://doc.rust-lang.org/cargo/guide/continuous-integration.html)
- [Semantic Versioning](https://semver.org/)

---

## Support

For issues with:
- **Workflows**: Check the troubleshooting section above
- **Horus Project**: See the main [README.md](../../README.md)
- **Gitea Actions**: Consult [Gitea documentation](https://docs.gitea.com)

For detailed line-by-line explanation of the workflows, see [WORKFLOW_EXPLAINED.md](./WORKFLOW_EXPLAINED.md).