# Gitea Actions Workflows

This directory contains automated workflows for NUPST's CI/CD pipeline.

## Workflows

### CI Workflow (`ci.yml`)

**Triggers:**

- Push to `main` branch
- Push to `migration/**` branches
- Pull requests to `main`

**Jobs:**

1. **Type Check & Lint**
   - Runs `deno check` for TypeScript validation
   - Runs `deno lint` (continues on error)
   - Runs `deno fmt --check` (continues on error)

2. **Build Test (Current Platform)**
   - Compiles for Linux x86_64 (host platform)
   - Tests binary execution (`--version` and `help`)

3. **Build All Platforms** (Main/Tags only)
   - Compiles all 5 platform binaries
   - Uploads as artifacts (30-day retention)
   - Only runs on `main` branch or tags

### Release Workflow (`release.yml`)

**Triggers:**

- Push tags matching `v*` (e.g., `v4.0.0`)

**Jobs:**

1. **Version Verification**
   - Extracts version from tag
   - Verifies `deno.json` version matches tag
   - Fails if mismatch detected

2. **Compilation**
   - Compiles binaries for all 5 platforms:
     - `nupst-linux-x64` (Linux x86_64)
     - `nupst-linux-arm64` (Linux ARM64)
     - `nupst-macos-x64` (macOS Intel)
     - `nupst-macos-arm64` (macOS Apple Silicon)
     - `nupst-windows-x64.exe` (Windows x64)

3. **Checksums**
   - Generates SHA256 checksums for all binaries
   - Creates `SHA256SUMS.txt`

4. **Release Creation**
   - Creates Gitea release with tag
   - Extracts release notes from CHANGELOG.md (if exists)
   - Uploads all binaries + checksums as release assets

## Creating a Release

### Prerequisites

1. Update version in `deno.json`:
   ```json
   {
     "version": "4.0.0"
   }
   ```

2. Update `CHANGELOG.md` with release notes (optional but recommended)

3. Commit all changes:
   ```bash
   git add .
   git commit -m "chore: bump version to 4.0.0"
   ```

### Release Process

1. Create and push a tag matching the version:
   ```bash
   git tag v4.0.0
   git push origin v4.0.0
   ```

2. Gitea Actions will automatically:
   - Verify version consistency
   - Compile all platform binaries
   - Generate checksums
   - Create release with binaries attached

3. Monitor the workflow:
   - Go to: `https://code.foss.global/serve.zone/nupst/actions`
   - Check the "Release" workflow run

### Manual Release (Fallback)

If workflows fail, you can create a release manually:

```bash
# Compile all binaries
bash scripts/compile-all.sh

# Generate checksums
cd dist/binaries
sha256sum * > SHA256SUMS.txt
cd ../..

# Create release on Gitea UI
# Upload binaries manually
```

## Troubleshooting

### Version Mismatch Error

If the release workflow fails with "Version mismatch":

- Ensure `deno.json` version matches the git tag
- Example: tag `v4.0.0` requires `"version": "4.0.0"` in deno.json

### Compilation Errors

If compilation fails:

1. Test locally: `bash scripts/compile-all.sh`
2. Check Deno version compatibility
3. Review TypeScript errors: `deno check mod.ts`

### Upload Failures

If binary upload fails:

1. Check Gitea Actions permissions
2. Verify `GITHUB_TOKEN` secret exists (auto-provided by Gitea)
3. Try manual release creation

## Workflow Secrets

The workflows use the following secrets:

- `GITHUB_TOKEN` - Auto-provided by Gitea Actions (no setup needed)

## Development

### Testing Workflows Locally

You can test compilation locally:

```bash
# Install Deno
curl -fsSL https://deno.land/install.sh | sh

# Test type checking
deno check mod.ts

# Test compilation
bash scripts/compile-all.sh

# Test binary
./dist/binaries/nupst-linux-x64 --version
```

### Modifying Workflows

After modifying workflows:

1. Test syntax: Use a YAML validator
2. Commit changes: `git add .gitea/workflows/`
3. Push to feature branch first to test CI
4. Merge to main once verified

## Links

- Gitea Actions Documentation: https://docs.gitea.com/usage/actions/overview
- Deno Compile Documentation: https://docs.deno.com/runtime/manual/tools/compiler
- NUPST Repository: https://code.foss.global/serve.zone/nupst