teal.fm
Your music, beautifully tracked. All yours. (coming soon)
teal.fm
teal-fm
atproto
1# GitHub Actions Workflows Documentation
2
3This document describes the CI/CD workflows configured for the Teal project.
4
5## Overview
6
7The project uses GitHub Actions for continuous integration, deployment, and security scanning. The workflows are designed to handle a polyglot codebase with Rust services, Node.js packages, and a React Native application.
8
9## Workflows
10
11### 🔧 CI (`ci.yml`)
12
13**Triggers:** Push/PR to `main` or `develop` branches
14
15**Purpose:** Primary continuous integration workflow that runs tests, linting, and type checking.
16
17**Jobs:**
18- **rust-check**: Formats, lints (clippy), and tests all Rust code in both `services/` and `apps/`
19- **node-check**: Type checking, linting, building, and testing Node.js packages
20- **lexicon-check**: Validates lexicon files and ensures generated code is up to date
21
22**Key Features:**
23- Caches Rust and Node.js dependencies for faster builds
24- Runs in parallel for optimal performance
25- Fails fast if any check fails
26
27### 🚀 Aqua (`aqua.yml`)
28
29**Triggers:** Push/PR to `main` with changes to `apps/aqua/**`
30
31**Purpose:** Builds and pushes the Aqua Rust application Docker image.
32
33**Features:**
34- Multi-platform builds (linux/amd64, linux/arm64)
35- Pushes to GitHub Container Registry (ghcr.io)
36- Only pushes on main branch (not PRs)
37- Uses GitHub Actions cache for Docker layers
38
39### 🤖 Cadet (`cadet.yml`)
40
41**Triggers:** Push/PR to `main` with changes to `services/cadet/**`
42
43**Purpose:** Builds and pushes the Cadet Rust service Docker image.
44
45**Features:**
46- Multi-platform builds (linux/amd64, linux/arm64)
47- Pushes to GitHub Container Registry (ghcr.io)
48- Only pushes on main branch (not PRs)
49- Uses GitHub Actions cache for Docker layers
50
51### 🔮 Amethyst (`amethyst.yml`)
52
53**Triggers:** Push/PR to `main` with changes to `apps/amethyst/**`
54
55**Purpose:** Builds the React Native/Expo application for different platforms.
56
57**Jobs:**
58- **build-web**: Builds web version and uploads artifacts
59- **build-ios**: Builds iOS version (only on main branch pushes, requires macOS runner)
60- **lint-and-test**: Type checking and testing
61
62**Features:**
63- Generates lexicons before building
64- Platform-specific builds
65- Artifact uploads for build assets
66
67### 🛠️ Services (`services.yml`)
68
69**Triggers:** Push/PR to `main` with changes to `services/**`
70
71**Purpose:** Dynamically detects and builds all services with Dockerfiles.
72
73**Jobs:**
74- **detect-services**: Scans for services with Dockerfiles
75- **build-service**: Matrix build for each detected service
76- **test-services**: Runs tests for all services
77
78**Features:**
79- Dynamic service detection
80- Skips special directories (target, migrations, types, .sqlx)
81- Per-service Docker caching
82- Multi-platform builds
83
84### 🎉 Release (`release.yml`)
85
86**Triggers:**
87- Push to tags matching `v*`
88- Manual workflow dispatch
89
90**Purpose:** Creates GitHub releases and builds production Docker images.
91
92**Jobs:**
93- **create-release**: Creates GitHub release with changelog
94- **build-and-release-aqua**: Builds and tags Aqua for release
95- **build-and-release-cadet**: Builds and tags Cadet for release
96- **release-other-services**: Builds other services (rocketman, satellite)
97- **build-and-release-amethyst**: Builds Amethyst and uploads to release
98
99**Features:**
100- Automatic changelog extraction
101- Production Docker tags (latest + version)
102- Release artifact uploads
103- Support for pre-releases (tags with `-`)
104
105### 🔒 Security (`security.yml`)
106
107**Triggers:**
108- Push/PR to `main` or `develop`
109- Daily at 2 AM UTC
110- Manual dispatch
111
112**Purpose:** Comprehensive security scanning and vulnerability detection.
113
114**Jobs:**
115- **rust-security-audit**: Uses `cargo audit` for Rust dependencies
116- **node-security-audit**: Uses `pnpm audit` for Node.js dependencies
117- **codeql-analysis**: GitHub's semantic code analysis
118- **docker-security-scan**: Trivy vulnerability scanning for Docker images
119- **secrets-scan**: TruffleHog for secrets detection
120
121**Features:**
122- Fails on high/critical vulnerabilities
123- SARIF upload for security tab integration
124- Historical scanning with git history
125
126## Configuration Files
127
128### Dependabot (`dependabot.yml`)
129
130Automated dependency updates for:
131- **npm**: Weekly updates for Node.js dependencies
132- **cargo**: Weekly updates for Rust dependencies (services + apps)
133- **github-actions**: Weekly updates for workflow actions
134- **docker**: Weekly updates for Docker base images
135
136**Schedule:** Monday-Tuesday mornings, staggered to avoid conflicts
137
138## Container Registry
139
140All Docker images are pushed to GitHub Container Registry:
141- `ghcr.io/[owner]/[repo]/aqua`
142- `ghcr.io/[owner]/[repo]/cadet`
143- `ghcr.io/[owner]/[repo]/[service-name]`
144
145**Tags:**
146- `latest`: Latest build from main branch
147- `sha-[commit]`: Specific commit builds
148- `v[version]`: Release builds
149- `pr-[number]`: Pull request builds (for testing)
150
151## Secrets and Permissions
152
153**Required secrets:**
154- `GITHUB_TOKEN`: Automatically provided (for registry access and releases)
155
156**Permissions used:**
157- `contents: read`: Read repository contents
158- `packages: write`: Push to GitHub Container Registry
159- `security-events: write`: Upload security scan results
160- `actions: read`: Access workflow information
161
162## Best Practices
163
1641. **Path-based triggers**: Workflows only run when relevant files change
1652. **Caching**: Aggressive caching for Rust, Node.js, and Docker layers
1663. **Multi-platform**: Docker images built for amd64 and arm64
1674. **Security-first**: Regular vulnerability scanning and secrets detection
1685. **Fail-fast**: Early termination on critical issues
1696. **Artifact preservation**: Build outputs stored for debugging/deployment
170
171## Usage Examples
172
173### Manual Release
174```bash
175# Tag and push for automatic release
176git tag v1.0.0
177git push origin v1.0.0
178
179# Or use workflow dispatch in GitHub UI
180```
181
182### Local Development
183```bash
184# Run the same checks locally
185pnpm rust:fmt
186pnpm rust:clippy
187pnpm typecheck
188pnpm test
189```
190
191### Debugging Failed Builds
1921. Check the Actions tab for detailed logs
1932. Download artifacts from successful builds
1943. Use the same commands locally with cached dependencies
195
196## Maintenance
197
198- **Weekly**: Review Dependabot PRs
199- **Monthly**: Update action versions if not auto-updated
200- **Quarterly**: Review and update security scanning tools
201- **As needed**: Add new services to release workflow matrix