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
|
## 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
|
## 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 │ │
|
│ │ CI Job │───►│ Release Job │ │
|
||||||
│ │ │ │ │ │ │ │
|
│ │ │ │ │ │
|
||||||
│ │ • Lint │ │ • Analyze │ │ • Multi-platform build │ │
|
│ │ • Lint │ │ • Analyze commits │ │
|
||||||
│ │ • Test │ │ commits │ │ (amd64, arm64) │ │
|
│ │ • Test │ │ • Bump version │ │
|
||||||
│ │ • Build │ │ • Bump version │ │ • Push to Docker Hub │ │
|
│ │ • Build │ │ • Update CHANGELOG │ │
|
||||||
│ │ • Commitlint│ │ • Update │ │ • Push to GHCR │ │
|
│ │ • Commitlint│ │ • Create tag │ │
|
||||||
│ │ │ │ CHANGELOG │ │ │ │
|
│ │ │ │ • Create Gitea release │ │
|
||||||
│ │ │ │ • Create tag │ │ │ │
|
│ └─────────────┘ └─────────────────────────────────────────────────┘ │
|
||||||
│ │ │ │ • GitHub release│ │ │ │
|
|
||||||
│ └─────────────┘ └─────────────────┘ └──────────────────────────┘ │
|
|
||||||
│ │
|
│ │
|
||||||
└─────────────────────────────────────────────────────────────────────────────┘
|
│ Note: Docker publishing temporarily disabled (runner lacks Docker) │
|
||||||
│
|
|
||||||
▼
|
|
||||||
┌─────────────────────────────────────────────────────────────────────────────┐
|
|
||||||
│ 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 │ │
|
|
||||||
│ └─────────────────────────────┘ └─────────────────────────────────┘ │
|
|
||||||
│ │
|
│ │
|
||||||
└─────────────────────────────────────────────────────────────────────────────┘
|
└─────────────────────────────────────────────────────────────────────────────┘
|
||||||
```
|
```
|
||||||
@@ -128,11 +112,20 @@ Located in `.releaserc.json`:
|
|||||||
"@semantic-release/changelog",
|
"@semantic-release/changelog",
|
||||||
"@semantic-release/npm",
|
"@semantic-release/npm",
|
||||||
"@semantic-release/git",
|
"@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
|
### 3. commitlint
|
||||||
|
|
||||||
Enforces conventional commits via:
|
Enforces conventional commits via:
|
||||||
@@ -149,12 +142,14 @@ Configuration in `commitlint.config.js`:
|
|||||||
|
|
||||||
### 4. Husky Git Hooks
|
### 4. Husky Git Hooks
|
||||||
|
|
||||||
| Hook | Purpose | Command |
|
| Hook | Purpose | Command |
|
||||||
| ------------ | ------------------------- | ------------------- |
|
| ------------ | ------------------------- | ------------------------------------ |
|
||||||
| `pre-commit` | Run linting before commit | `npm run lint` |
|
| `pre-commit` | Run linting + secret scan | `npm run lint` + `gitleaks protect` |
|
||||||
| `commit-msg` | Validate commit message | `commitlint --edit` |
|
| `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`)
|
#### CI Workflow (`.github/workflows/ci.yml`)
|
||||||
|
|
||||||
@@ -193,8 +188,9 @@ Runs on: Push to master (excluding [skip ci] commits)
|
|||||||
│ Release Job │
|
│ Release Job │
|
||||||
├───────────────────────────────────────────────────────────┤
|
├───────────────────────────────────────────────────────────┤
|
||||||
│ 1. Checkout (fetch-depth: 0 for full history) │
|
│ 1. Checkout (fetch-depth: 0 for full history) │
|
||||||
│ 2. Setup Node.js 20 │
|
│ 2. Setup Node.js 24 │
|
||||||
│ 3. Install dependencies (root + backend) │
|
│ 3. Install dependencies (root + backend) │
|
||||||
|
│ - Uses --prefer-offline --no-audit --no-fund │
|
||||||
│ 4. Lint │
|
│ 4. Lint │
|
||||||
│ 5. Run tests (root + backend) │
|
│ 5. Run tests (root + backend) │
|
||||||
│ 6. Build │
|
│ 6. Build │
|
||||||
@@ -203,75 +199,41 @@ Runs on: Push to master (excluding [skip ci] commits)
|
|||||||
│ - Bump version │
|
│ - Bump version │
|
||||||
│ - Update CHANGELOG.md │
|
│ - Update CHANGELOG.md │
|
||||||
│ - Create git tag │
|
│ - Create git tag │
|
||||||
│ - Create GitHub release │
|
│ - Create Gitea 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) │
|
|
||||||
└───────────────────────────────────────────────────────────┘
|
└───────────────────────────────────────────────────────────┘
|
||||||
```
|
```
|
||||||
|
|
||||||
|
Note: Docker build job temporarily disabled (runner lacks Docker support).
|
||||||
|
|
||||||
#### Staging Workflow (`.github/workflows/staging.yml`)
|
#### Staging Workflow (`.github/workflows/staging.yml`)
|
||||||
|
|
||||||
Runs on: Push to staging branch
|
Runs on: Push to staging branch
|
||||||
|
|
||||||
```
|
**Status: Temporarily disabled** - Requires Docker support on runner.
|
||||||
┌───────────────────────────────────────────────────────────┐
|
|
||||||
│ Staging Deploy Job │
|
|
||||||
├───────────────────────────────────────────────────────────┤
|
|
||||||
│ 1. Checkout │
|
|
||||||
│ 2. Install + Lint + Test + Build │
|
|
||||||
│ 3. Build Docker image (multi-platform) │
|
|
||||||
│ 4. Push with tag: staging │
|
|
||||||
└───────────────────────────────────────────────────────────┘
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Nightly Workflow (`.github/workflows/nightly.yml`)
|
#### Nightly Workflow (`.github/workflows/nightly.yml`)
|
||||||
|
|
||||||
Runs on: Schedule (daily at 02:00 UTC)
|
Runs on: Schedule (daily at 02:00 UTC)
|
||||||
|
|
||||||
```
|
**Status: Temporarily disabled** - Requires Docker support on runner.
|
||||||
┌───────────────────────────────────────────────────────────┐
|
|
||||||
│ 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 │
|
|
||||||
└───────────────────────────────────────────────────────────┘
|
|
||||||
```
|
|
||||||
|
|
||||||
## Docker Image Tags
|
## Docker Image Tags
|
||||||
|
|
||||||
|
**Status: Temporarily disabled** - Docker publishing requires runner with Docker-in-Docker support.
|
||||||
|
|
||||||
| Tag | Registry | Description | Update Frequency |
|
| Tag | Registry | Description | Update Frequency |
|
||||||
| ------------ | -------- | --------------------- | ---------------------- |
|
| ------------ | -------- | --------------------- | ---------------------- |
|
||||||
| `latest` | Both | Latest stable release | Every release |
|
| `latest` | Both | Latest stable release | Every release |
|
||||||
| `v1.0.0` | Both | Specific version | Immutable |
|
| `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 |
|
| `staging` | Both | Staging environment | Every staging push |
|
||||||
| `nightly` | Both | Latest nightly build | Daily |
|
| `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
|
```bash
|
||||||
# Docker Hub
|
# Docker Hub
|
||||||
docker pull username/cv-app:latest
|
docker pull username/cv-app:latest
|
||||||
docker pull username/cv-app:v1.0.0
|
docker pull username/cv-app:v1.0.0
|
||||||
docker pull username/cv-app:staging
|
|
||||||
docker pull username/cv-app:nightly
|
|
||||||
|
|
||||||
# GitHub Container Registry
|
# GitHub Container Registry
|
||||||
docker pull ghcr.io/owner/cv-app:latest
|
docker pull ghcr.io/owner/cv-app:latest
|
||||||
@@ -280,11 +242,11 @@ docker pull ghcr.io/owner/cv-app:v1.0.0
|
|||||||
|
|
||||||
## Environments
|
## Environments
|
||||||
|
|
||||||
| Environment | Branch | Trigger | Docker Tag |
|
| Environment | Branch | Trigger | Status |
|
||||||
| ----------- | --------- | ----------------------------------- | ------------------------------- |
|
| ----------- | --------- | ----------------------------------- | ---------------------------- |
|
||||||
| Production | `master` | semantic-release (feat/fix commits) | `latest`, `vX.Y.Z` |
|
| Production | `master` | semantic-release (feat/fix commits) | Active (release only) |
|
||||||
| Staging | `staging` | Push to branch | `staging` |
|
| Staging | `staging` | Push to branch | Disabled (Docker required) |
|
||||||
| Nightly | `master` | Daily at 02:00 UTC | `nightly`, `edge`, `YYYY-MM-DD` |
|
| Nightly | `master` | Daily at 02:00 UTC | Disabled (Docker required) |
|
||||||
|
|
||||||
## Release Flow Example
|
## Release Flow Example
|
||||||
|
|
||||||
@@ -296,6 +258,7 @@ Developer commits: feat(admin): add export functionality
|
|||||||
│ Git Hook Runs │
|
│ Git Hook Runs │
|
||||||
│ (pre-commit) │
|
│ (pre-commit) │
|
||||||
│ • npm run lint │
|
│ • npm run lint │
|
||||||
|
│ • gitleaks │
|
||||||
└─────────────────┘
|
└─────────────────┘
|
||||||
│
|
│
|
||||||
▼
|
▼
|
||||||
@@ -361,40 +324,23 @@ Developer commits: feat(admin): add export functionality
|
|||||||
│
|
│
|
||||||
▼
|
▼
|
||||||
┌─────────────────┐
|
┌─────────────────┐
|
||||||
│ GitHub Release │
|
│ Gitea Release │
|
||||||
│ created │
|
│ created │
|
||||||
│ with notes │
|
│ 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
|
## Required Secrets
|
||||||
|
|
||||||
Configure these in GitHub repository settings → Secrets and variables → Actions:
|
Configure these in Gitea repository settings → Settings → Secrets:
|
||||||
|
|
||||||
| Secret | Description | Required For |
|
| Secret | Description | Required For |
|
||||||
| -------------------- | ------------------------ | ------------------- |
|
| -------------------- | ------------------------ | ------------------- |
|
||||||
| `DOCKERHUB_USERNAME` | Docker Hub username | Docker Hub push |
|
| `DOCKERHUB_USERNAME` | Docker Hub username | Docker Hub push |
|
||||||
| `DOCKERHUB_TOKEN` | Docker Hub access token | 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
|
Note: Docker publishing is currently disabled until runner supports Docker-in-Docker.
|
||||||
|
|
||||||
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
|
|
||||||
|
|
||||||
## Local Development
|
## 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.
|
**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
|
### Version Not Bumping
|
||||||
|
|
||||||
**Cause**: semantic-release requires conventional commits with proper types.
|
**Cause**: semantic-release requires conventional commits with proper types.
|
||||||
|
|||||||
Reference in New Issue
Block a user