ci-patterns ยท diff

git:20251007.8d64d27 to v1.0.0

3 added, 0 removed. Audit A to A.

What this update changes in the checks

No check changed: every fixed check gives the same answer before and after this update.

A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.

---
description: CI/CD patterns and automation best practices
+ version: "1.0.0"
+ lastUpdated: "2025-10-08"
+ dependencies: ["quality-standards", "bun-runtime"]
---
# CI/CD Patterns
## Local CI Execution
### One-Click Commands
```bash
# Full CI pipeline
bun run ci
# Quick CI (skip slow checks)
bun run ci:quick
# Interactive CI with reporting
bun run ci:local
# Just tests
bun test
```
## CI Script Structure
### Standard CI Pipeline
```typescript
const steps = [
{
name: 'Security Scan',
command: ['sg', 'scan', 'src/'],
timeout: 30000,
required: true
},
{
name: 'SQL Migration Validation',
command: ['bun', 'run', 'scripts/validate-migrations.ts'],
timeout: 10000,
required: true
},
{
name: 'Lint Code',
command: ['bun', 'run', 'lint'],
timeout: 30000,
required: false
},
{
name: 'Type Check',
command: ['bun', 'x', 'tsc', '--noEmit'],
timeout: 60000,
required: false
},
{
name: 'Unit Tests',
command: ['bun', 'test', 'tests/unit'],
timeout: 120000,
required: true
},
{
name: 'Integration Tests',
command: ['bun', 'test', 'tests/integration'],
timeout: 180000,
required: true
},
{
name: 'Build',
command: ['bun', 'run', 'build:worker'],
timeout: 60000,
required: true
}
];
```
## GitHub Actions Patterns
### Workflow Structure
```yaml
name: CI Pipeline
on:
push:
branches: [main, develop]
pull_request:
branches: [main]
# Cancel outdated runs
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
jobs:
security:
name: Security Gate
runs-on: ubuntu-latest
timeout-minutes: 5
steps:
- uses: actions/checkout@v4
- uses: oven-sh/setup-bun@v2
with:
bun-version: 1.2.23
- run: sg scan src/
test:
name: Tests
needs: security # Block on security
runs-on: ubuntu-latest
timeout-minutes: 15
steps:
- uses: actions/checkout@v4
- uses: oven-sh/setup-bun@v2
- run: bun install
- run: bun test
build:
name: Build
needs: [security, test]
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: oven-sh/setup-bun@v2
- run: bun install
- run: bun run build:worker
```
## CI Best Practices
### Job Dependencies
```yaml
# Sequential execution
jobs:
security:
# Runs first
test:
needs: security # Waits for security
build:
needs: [security, test] # Waits for both
deploy:
needs: build # Final step
```
### Caching
```yaml
- name: Cache Bun dependencies
uses: actions/cache@v4
with:
path: ~/.bun/install/cache
key: ${{ runner.os }}-bun-${{ hashFiles('**/bun.lockb') }}
restore-keys: |
${{ runner.os }}-bun-
```
### Timeouts
```yaml
jobs:
test:
timeout-minutes: 15 # Job-level timeout
steps:
- run: bun test --timeout 10000 # Command-level timeout
```
### Artifact Upload
```yaml
- name: Upload build artifacts
uses: actions/upload-artifact@v4
with:
name: build-artifacts
path: dist/
retention-days: 7
```
## Error Handling
### Required vs Optional Steps
```typescript
interface CIStep {
name: string;
command: string[];
required: boolean; // Fail CI if this fails
timeout?: number;
}
async function executeStep(step: CIStep) {
try {
await runCommand(step.command, step.timeout);
} catch (error) {
if (step.required) {
throw error; // Fail CI
} else {
console.warn(`Optional step failed: ${step.name}`);
}
}
}
```
### Retry Logic
```typescript
async function runWithRetry(
command: string[],
maxRetries: number = 3
): Promise<boolean> {
for (let i = 0; i < maxRetries; i++) {
try {
await runCommand(command);
return true;
} catch (error) {
if (i === maxRetries - 1) throw error;
console.log(`Retry ${i + 1}/${maxRetries}...`);
await new Promise(r => setTimeout(r, 1000 * (i + 1)));
}
}
return false;
}
```
## Reporting
### CI Report Structure
```typescript
interface CIReport {
timestamp: string;
duration: number;
summary: {
passed: number;
failed: number;
skipped: number;
total: number;
};
results: Array<{
step: string;
status: 'pass' | 'fail' | 'skip';
duration: number;
error?: string;
}>;
}
```
### Console Output
```typescript
function printReport(report: CIReport) {
console.log('\n' + 'โ•'.repeat(70));
console.log('๐Ÿ“Š CI PIPELINE REPORT');
console.log('โ•'.repeat(70));
console.log(`\n๐Ÿ“ˆ Results: ${report.summary.passed} passed, ${report.summary.failed} failed`);
console.log(`โฑ๏ธ Duration: ${(report.duration / 1000).toFixed(2)}s`);
if (report.summary.failed > 0) {
console.log('\nโŒ Failed Steps:');
report.results
.filter(r => r.status === 'fail')
.forEach(r => console.log(` โ€ข ${r.step}: ${r.error}`));
}
}
```
## Package.json Scripts
### CI Scripts Pattern
```json
{
"scripts": {
"ci": "bun run ci:full",
"ci:full": "bun run security && bun run lint && bun run type-check && bun run test && bun run build",
"ci:quick": "bun run security && bun run test:fast",
"ci:local": "bun run scripts/ci-local.ts",
"security": "sg scan src/",
"security:migrations": "bun run scripts/validate-migrations.ts",
"test": "bun test",
"test:unit": "bun test tests/unit",
"test:integration": "bun test tests/integration",
"test:fast": "bun test --concurrent --randomize",
"lint": "bun run scripts/lint.ts",
"format": "bun run scripts/format.ts",
"type-check": "tsc --noEmit",
"build": "bun build src/index.ts --outdir dist",
"build:worker": "bun build src/index.ts --outdir dist --minify"
}
}
```
## Key Files
- [CI Local Script](mdc:scripts/ci-local.ts) - Local CI implementation
- [GitHub Actions](mdc:.github/workflows/ci.yml) - CI workflow
- [Build Automation](mdc:scripts/automation/build-and-test.ts) - Build pipeline
- [Package Scripts](mdc:package.json) - NPM scripts
## Rules Summary
1. โœ… Always use timeouts (job and command level)
2. โœ… Block on security gate (required)
3. โœ… Cache dependencies for speed
4. โœ… Use concurrency control
5. โœ… Report results clearly
6. โœ… Separate required vs optional steps
7. โœ… Cleanup processes after CI
8. โœ… Version pin critical tools
9. โŒ Never skip security checks
10. โŒ Never run CI without timeouts