PeterNashaat/horus
1
0
Fork 0
forked from herocode/horus
Code Pull Requests Actions Releases Activity

Add CI/CD workflows with docs

Browse Source
This commit is contained in:
peternashaat
2025-11-19 08:45:56 +00:00
parent e925f4c974
commit be920e1eb6
4 changed files with 1454 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

391
.gitea/workflows/README.md Normal file
View File

@@ -0,0 +1,391 @@
# 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).