git.stella-ops.org/docs/releases/RELEASE_PROCESS.md

# StellaOps Release Process

This document describes the release process for StellaOps suite and module releases.

## Overview

StellaOps uses automated CI/CD pipelines for releases:

| Release Type | Workflow | Trigger |
|--------------|----------|---------|
| Module | `.gitea/workflows/module-publish.yml` | Tag or manual dispatch |
| Suite | `.gitea/workflows/release-suite.yml` | Tag or manual dispatch |

---

## Module Release Process

### Prerequisites

- [ ] All tests passing on main branch
- [ ] CHANGELOG.md updated with changes
- [ ] Version bumped in module's `version.txt` (if applicable)
- [ ] Breaking changes documented

### Steps

#### Option A: Tag-based Release

```bash
# Create and push tag
git tag module-authority-v1.2.3
git push origin module-authority-v1.2.3
```

The pipeline will automatically:
1. Parse module name and version from tag
2. Build the module
3. Publish NuGet package to Gitea registry
4. Build and push container image (if applicable)

#### Option B: Manual Dispatch

1. Navigate to **Actions** > **Module Publish**
2. Click **Run workflow**
3. Select:
   - **Module**: e.g., `Authority`
   - **Version**: e.g., `1.2.3`
   - **Publish NuGet**: `true`
   - **Publish Container**: `true`
4. Click **Run**

### Artifacts Published

| Artifact | Location |
|----------|----------|
| NuGet | `git.stella-ops.org/api/packages/stella-ops.org/nuget/index.json` |
| Container | `git.stella-ops.org/stella-ops.org/{module}:{version}` |

---

## Suite Release Process

### Prerequisites

- [ ] All module versions finalized
- [ ] Integration tests passing
- [ ] Security scan completed
- [ ] CHANGELOG.md updated
- [ ] Compatibility matrix documented
- [ ] Codename selected (see [codenames.md](codenames.md))

### Pre-Release Checklist

```markdown
- [ ] All P1 issues resolved
- [ ] Performance benchmarks meet SLOs
- [ ] Documentation updated
- [ ] Migration guide prepared
- [ ] Release notes drafted
- [ ] Security advisory review complete
- [ ] Air-gap bundle tested
- [ ] Helm chart validated
```

### Steps

#### Option A: Tag-based Release

```bash
# Create and push tag
git tag suite-2026.04-nova
git push origin suite-2026.04-nova
```

#### Option B: Manual Dispatch

1. Navigate to **Actions** > **Suite Release**
2. Click **Run workflow**
3. Fill in:
   - **Version**: e.g., `2026.04`
   - **Codename**: e.g., `Nova`
   - **Channel**: `edge`, `stable`, or `lts`
   - **Skip tests**: `false` (default)
   - **Dry run**: `false` for actual release
4. Click **Run**

### Pipeline Stages

```
validate → test-gate → build-modules → build-containers
                    ↘              ↓
                     build-cli → build-helm → release-manifest → create-release → summary
```

1. **Validate** - Check version format, resolve inputs
2. **Test Gate** - Run unit, architecture, and contract tests
3. **Build Modules** - Build all 9 modules (matrix)
4. **Build Containers** - Push container images (9 modules)
5. **Build CLI** - Build for 5 platforms
6. **Build Helm** - Package Helm chart
7. **Release Manifest** - Generate `suite-{version}.yaml`
8. **Create Release** - Create Gitea release with artifacts
9. **Summary** - Generate summary report

### Artifacts Published

| Artifact | Files |
|----------|-------|
| Container images | 9 modules × 3 tags (version, channel, latest) |
| CLI binaries | 5 platforms (linux-x64, linux-arm64, win-x64, osx-x64, osx-arm64) |
| Helm chart | `stellaops-{version}.tgz` |
| Release manifest | `suite-{version}.yaml` |
| Checksums | `SHA256SUMS-{version}.txt` |

---

## Release Channels

### Edge

- Pre-release builds
- May contain experimental features
- Not recommended for production
- Triggered by: `channel: edge` or tag without `-stable`/`-lts`

### Stable

- Production-ready releases
- Thoroughly tested
- 9 months of support (feature releases)
- Triggered by: `channel: stable`

### LTS (Long Term Support)

- April releases only (XX.04)
- 5 years of security updates
- 3 years of standard support
- Triggered by: `channel: lts`

---

## Rollback Procedures

### Container Rollback

```bash
# Pull previous version
docker pull git.stella-ops.org/stella-ops.org/authority:2025.10

# Update deployment
kubectl set image deployment/authority authority=git.stella-ops.org/stella-ops.org/authority:2025.10
```

### Helm Rollback

```bash
# List releases
helm history stellaops

# Rollback to previous revision
helm rollback stellaops 1
```

### Database Rollback

1. Stop all services
2. Restore database from backup
3. Deploy previous version
4. Verify data integrity

**Important**: Always test rollback procedures in staging before production.

---

## Hotfix Process

For critical security fixes:

1. Create hotfix branch from release tag
   ```bash
   git checkout -b hotfix/2026.04.1 suite-2026.04
   ```

2. Apply fix and test

3. Tag hotfix release
   ```bash
   git tag suite-2026.04.1
   git push origin suite-2026.04.1
   ```

4. Cherry-pick fix to main branch

---

## Post-Release Tasks

- [ ] Verify artifacts in registry
- [ ] Update documentation site
- [ ] Send release announcement
- [ ] Update compatibility matrix
- [ ] Monitor for issues (24-48 hours)
- [ ] Update roadmap

---

## Troubleshooting

### Build Failures

1. Check test results in artifacts
2. Review workflow logs
3. Verify secrets are configured (GITEA_TOKEN)

### Push Failures

1. Verify registry authentication
2. Check network connectivity
3. Ensure no conflicting tags exist

### Common Issues

| Issue | Resolution |
|-------|------------|
| Tag already exists | Delete tag and recreate, or use next version |
| NuGet push fails | Check package already exists, use `--skip-duplicate` |
| Container push fails | Verify registry login, check image size limits |

---

## Related Documentation

- [Versioning Strategy](VERSIONING.md)
- [Codename Registry](codenames.md)
- [CI/CD Workflows](../../.gitea/workflows/)