diff --git a/docs/release-engineering.md b/docs/release-engineering.md index 48806f5..1418554 100644 --- a/docs/release-engineering.md +++ b/docs/release-engineering.md @@ -4,7 +4,7 @@ ## Overview -This project uses a fully automated release engineering pipeline powered by **semantic-release**, **commitlint**, and **GitHub Actions**. The pipeline handles versioning, changelog generation, Docker image publishing, and multi-environment deployments. +This project uses a fully automated release engineering pipeline powered by **semantic-release**, **commitlint**, and **Gitea Actions**. The pipeline handles versioning, changelog generation, and releases. Docker publishing is currently disabled pending runner configuration. ## Architecture @@ -22,36 +22,20 @@ This project uses a fully automated release engineering pipeline powered by **se │ ▼ ┌─────────────────────────────────────────────────────────────────────────────┐ -│ GitHub Actions Pipeline │ +│ Gitea Actions Pipeline │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ -│ ┌─────────────┐ ┌─────────────────┐ ┌──────────────────────────┐ │ -│ │ CI Job │───►│ Release Job │───►│ Docker Build Job │ │ -│ │ │ │ │ │ │ │ -│ │ • Lint │ │ • Analyze │ │ • Multi-platform build │ │ -│ │ • Test │ │ commits │ │ (amd64, arm64) │ │ -│ │ • Build │ │ • Bump version │ │ • Push to Docker Hub │ │ -│ │ • Commitlint│ │ • Update │ │ • Push to GHCR │ │ -│ │ │ │ CHANGELOG │ │ │ │ -│ │ │ │ • Create tag │ │ │ │ -│ │ │ │ • GitHub release│ │ │ │ -│ └─────────────┘ └─────────────────┘ └──────────────────────────┘ │ +│ ┌─────────────┐ ┌─────────────────────────────────────────────────┐ │ +│ │ CI Job │───►│ Release Job │ │ +│ │ │ │ │ │ +│ │ • Lint │ │ • Analyze commits │ │ +│ │ • Test │ │ • Bump version │ │ +│ │ • Build │ │ • Update CHANGELOG │ │ +│ │ • Commitlint│ │ • Create tag │ │ +│ │ │ │ • Create Gitea release │ │ +│ └─────────────┘ └─────────────────────────────────────────────────┘ │ │ │ -└─────────────────────────────────────────────────────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────────────────────────────────────────┐ -│ Registries │ -├─────────────────────────────────────────────────────────────────────────────┤ -│ │ -│ ┌─────────────────────────────┐ ┌─────────────────────────────────┐ │ -│ │ Docker Hub │ │ GitHub Container Registry │ │ -│ │ │ │ │ │ -│ │ username/cv-app:latest │ │ ghcr.io/owner/cv-app:latest │ │ -│ │ username/cv-app:v1.0.0 │ │ ghcr.io/owner/cv-app:v1.0.0 │ │ -│ │ username/cv-app:staging │ │ ghcr.io/owner/cv-app:staging │ │ -│ │ username/cv-app:nightly │ │ ghcr.io/owner/cv-app:nightly │ │ -│ └─────────────────────────────┘ └─────────────────────────────────┘ │ +│ Note: Docker publishing temporarily disabled (runner lacks Docker) │ │ │ └─────────────────────────────────────────────────────────────────────────────┘ ``` @@ -128,11 +112,20 @@ Located in `.releaserc.json`: "@semantic-release/changelog", "@semantic-release/npm", "@semantic-release/git", - "@semantic-release/github" + [ + "@semantic-release/github", + { + "successCommentCondition": false, + "failCommentCondition": false, + "releasedLabels": false + } + ] ] } ``` +Note: The `successCommentCondition` and `failCommentCondition` are set to `false` for Gitea compatibility (Gitea lacks GitHub's GraphQL API). + ### 3. commitlint Enforces conventional commits via: @@ -149,12 +142,14 @@ Configuration in `commitlint.config.js`: ### 4. Husky Git Hooks -| Hook | Purpose | Command | -| ------------ | ------------------------- | ------------------- | -| `pre-commit` | Run linting before commit | `npm run lint` | -| `commit-msg` | Validate commit message | `commitlint --edit` | +| Hook | Purpose | Command | +| ------------ | ------------------------- | ------------------------------------ | +| `pre-commit` | Run linting + secret scan | `npm run lint` + `gitleaks protect` | +| `commit-msg` | Validate commit message | `commitlint --edit` | -### 5. GitHub Actions Workflows +Note: Gitleaks scans for secrets before commit. If not installed locally, it's skipped gracefully. + +### 5. Gitea Actions Workflows #### CI Workflow (`.github/workflows/ci.yml`) @@ -193,8 +188,9 @@ Runs on: Push to master (excluding [skip ci] commits) │ Release Job │ ├───────────────────────────────────────────────────────────┤ │ 1. Checkout (fetch-depth: 0 for full history) │ -│ 2. Setup Node.js 20 │ +│ 2. Setup Node.js 24 │ │ 3. Install dependencies (root + backend) │ +│ - Uses --prefer-offline --no-audit --no-fund │ │ 4. Lint │ │ 5. Run tests (root + backend) │ │ 6. Build │ @@ -203,75 +199,41 @@ Runs on: Push to master (excluding [skip ci] commits) │ - Bump version │ │ - Update CHANGELOG.md │ │ - Create git tag │ -│ - Create GitHub release │ -└───────────────────────────────────────────────────────────┘ - │ - ▼ -┌───────────────────────────────────────────────────────────┐ -│ Docker Build Job │ -├───────────────────────────────────────────────────────────┤ -│ 1. Checkout │ -│ 2. Get version from git tag │ -│ 3. Setup QEMU (for multi-platform) │ -│ 4. Setup Docker Buildx │ -│ 5. Login to Docker Hub │ -│ 6. Login to GHCR │ -│ 7. Build and push (amd64 + arm64) │ +│ - Create Gitea release │ └───────────────────────────────────────────────────────────┘ ``` +Note: Docker build job temporarily disabled (runner lacks Docker support). + #### Staging Workflow (`.github/workflows/staging.yml`) Runs on: Push to staging branch -``` -┌───────────────────────────────────────────────────────────┐ -│ Staging Deploy Job │ -├───────────────────────────────────────────────────────────┤ -│ 1. Checkout │ -│ 2. Install + Lint + Test + Build │ -│ 3. Build Docker image (multi-platform) │ -│ 4. Push with tag: staging │ -└───────────────────────────────────────────────────────────┘ -``` +**Status: Temporarily disabled** - Requires Docker support on runner. #### Nightly Workflow (`.github/workflows/nightly.yml`) Runs on: Schedule (daily at 02:00 UTC) -``` -┌───────────────────────────────────────────────────────────┐ -│ Nightly Build Job │ -├───────────────────────────────────────────────────────────┤ -│ 1. Checkout master │ -│ 2. Get current date │ -│ 3. Install + Build │ -│ 4. Build Docker image (multi-platform) │ -│ 5. Push with tags: nightly, edge, YYYY-MM-DD │ -└───────────────────────────────────────────────────────────┘ -``` +**Status: Temporarily disabled** - Requires Docker support on runner. ## Docker Image Tags +**Status: Temporarily disabled** - Docker publishing requires runner with Docker-in-Docker support. + | Tag | Registry | Description | Update Frequency | | ------------ | -------- | --------------------- | ---------------------- | | `latest` | Both | Latest stable release | Every release | | `v1.0.0` | Both | Specific version | Immutable | -| `1.0` | Both | Major.minor | Points to latest patch | -| `1` | Both | Major version | Points to latest minor | | `staging` | Both | Staging environment | Every staging push | | `nightly` | Both | Latest nightly build | Daily | -| `edge` | Both | Alias for nightly | Daily | -| `2026-02-20` | Both | Date-specific nightly | Immutable | -### Pulling Images +### Pulling Images (when Docker publishing is enabled) ```bash # Docker Hub docker pull username/cv-app:latest docker pull username/cv-app:v1.0.0 -docker pull username/cv-app:staging -docker pull username/cv-app:nightly # GitHub Container Registry docker pull ghcr.io/owner/cv-app:latest @@ -280,11 +242,11 @@ docker pull ghcr.io/owner/cv-app:v1.0.0 ## Environments -| Environment | Branch | Trigger | Docker Tag | -| ----------- | --------- | ----------------------------------- | ------------------------------- | -| Production | `master` | semantic-release (feat/fix commits) | `latest`, `vX.Y.Z` | -| Staging | `staging` | Push to branch | `staging` | -| Nightly | `master` | Daily at 02:00 UTC | `nightly`, `edge`, `YYYY-MM-DD` | +| Environment | Branch | Trigger | Status | +| ----------- | --------- | ----------------------------------- | ---------------------------- | +| Production | `master` | semantic-release (feat/fix commits) | Active (release only) | +| Staging | `staging` | Push to branch | Disabled (Docker required) | +| Nightly | `master` | Daily at 02:00 UTC | Disabled (Docker required) | ## Release Flow Example @@ -296,6 +258,7 @@ Developer commits: feat(admin): add export functionality │ Git Hook Runs │ │ (pre-commit) │ │ • npm run lint │ + │ • gitleaks │ └─────────────────┘ │ ▼ @@ -361,40 +324,23 @@ Developer commits: feat(admin): add export functionality │ ▼ ┌─────────────────┐ - │ GitHub Release │ + │ Gitea Release │ │ created │ │ with notes │ └─────────────────┘ - │ - ▼ - ┌─────────────────────────────────┐ - │ Docker images built and │ - │ pushed to: │ - │ │ - │ • username/cv-app:latest │ - │ • username/cv-app:v1.1.0 │ - │ • ghcr.io/owner/cv-app:latest │ - │ • ghcr.io/owner/cv-app:v1.1.0 │ - └─────────────────────────────────┘ ``` ## Required Secrets -Configure these in GitHub repository settings → Secrets and variables → Actions: +Configure these in Gitea repository settings → Settings → Secrets: | Secret | Description | Required For | | -------------------- | ------------------------ | ------------------- | | `DOCKERHUB_USERNAME` | Docker Hub username | Docker Hub push | | `DOCKERHUB_TOKEN` | Docker Hub access token | Docker Hub push | -| `GITHUB_TOKEN` | GitHub token (automatic) | GHCR push, releases | +| `GITHUB_TOKEN` | Gitea token (automatic) | Releases | -### Creating Docker Hub Token - -1. Go to Docker Hub → Account Settings → Security -2. Click "New Access Token" -3. Name: `cv-app-github-actions` -4. Permissions: Read, Write, Delete -5. Copy token and add to GitHub secrets +Note: Docker publishing is currently disabled until runner supports Docker-in-Docker. ## Local Development @@ -449,16 +395,6 @@ git commit -m "feat(ui): add new button" **Solution**: Ensure you have `feat`, `fix`, or `perf` commits since last release. -### Docker Push Fails - -**Error**: `denied: requested access to the resource is denied` - -**Fix**: - -1. Verify `DOCKERHUB_USERNAME` and `DOCKERHUB_TOKEN` secrets -2. Ensure Docker Hub token has Write permission -3. Check Docker Hub repository exists (or enable auto-create) - ### Version Not Bumping **Cause**: semantic-release requires conventional commits with proper types.