docs: update release-engineering documentation
- Reflect Gitea Actions instead of GitHub Actions - Document npm install optimization flags - Add gitleaks to pre-commit hook documentation - Update semantic-release config for Gitea compatibility - Mark Docker workflows as temporarily disabled - Update pipeline diagrams and environment table
This commit is contained in:
Tuan-Dat Tran
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user