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 - Continuous Integration workflow
2. 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:

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

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

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

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

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

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:

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

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

retention-days: 30  # Keep for 30 days instead of 7

Adding Build Matrix

To build for multiple platforms, add a matrix strategy:

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:

# List recent tags
git tag -l

# Show tag details
git show v1.0.0

Workflow Badges

Add status badges to your README:

![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:

# 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
• GitHub Actions Syntax (Gitea is compatible)
• Rust CI Best Practices
• Semantic Versioning

---

Support

For issues with:

• Workflows: Check the troubleshooting section above
• Horus Project: See the main README.md
• Gitea Actions: Consult Gitea documentation

For detailed line-by-line explanation of the workflows, see WORKFLOW_EXPLAINED.md.