Skip to content

Commit a25a220

Browse files
Copilotal7566
Copilot
and
al7566
committed
Add CI/CD integration guide for key management system
Co-authored-by: al7566 <215473224+al7566@users.noreply.github.com>
1 parent e822d5a commit a25a220

File tree

1 file changed

+360
-0
lines changed

1 file changed

+360
-0
lines changed

‎docs/KEY_MANAGEMENT_INTEGRATION.md‎

Lines changed: 360 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,360 @@
1+
# Integration Example: Adding Key Management to CI/CD
2+
3+
This document shows a complete example of integrating the key management system into the existing CI workflow.
4+
5+
## Current CI Workflow
6+
7+
The repository already has a CI workflow at `.github/workflows/ci.yml` that:
8+
1. Runs tests and builds
9+
2. Builds Docker images
10+
3. Deploys to ECR and GHCR
11+
12+
## Adding Key Management
13+
14+
### Option 1: End-of-Build Integration (Recommended)
15+
16+
Add key management after the build but before deployment:
17+
18+
```yaml
19+
# In .github/workflows/ci.yml
20+
21+
jobs:
22+
# Existing jobs
23+
test-build:
24+
name: Test and Build
25+
uses: ./.github/workflows/test-build.yml
26+
secrets: inherit
27+
28+
# NEW: Add key management
29+
manage-keys:
30+
name: Manage API Keys
31+
needs: test-build
32+
if: github.event_name == 'push' && (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/staging')
33+
uses: ./.github/workflows/key-manager.yml
34+
secrets: inherit
35+
with:
36+
command: 'scan'
37+
dry_run: false
38+
39+
# Existing deployment jobs - now depend on key management
40+
build-amd64:
41+
name: Build AMD64
42+
needs: [test-build, manage-keys] # Added manage-keys dependency
43+
if: github.event_name == 'push' && (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/staging')
44+
runs-on: blacksmith-8vcpu-ubuntu-2404
45+
# ... rest of the job
46+
```
47+
48+
### Option 2: Separate Workflow
49+
50+
Create a new workflow that runs on a schedule:
51+
52+
```yaml
53+
# .github/workflows/key-audit.yml
54+
name: Weekly Key Audit
55+
56+
on:
57+
schedule:
58+
- cron: '0 0 * * 0' # Every Sunday at midnight
59+
workflow_dispatch: # Allow manual trigger
60+
61+
jobs:
62+
audit-keys:
63+
name: Audit Repository Keys
64+
uses: ./.github/workflows/key-manager.yml
65+
secrets: inherit
66+
with:
67+
command: 'check'
68+
dry_run: true
69+
```
70+
71+
### Option 3: Pre-Deployment
72+
73+
Add to deployment workflows:
74+
75+
```yaml
76+
# Before deploying
77+
jobs:
78+
prepare-environment:
79+
name: Prepare Environment
80+
uses: ./.github/workflows/key-manager.yml
81+
secrets: inherit
82+
with:
83+
command: 'inject'
84+
dry_run: false
85+
86+
deploy:
87+
name: Deploy
88+
needs: prepare-environment
89+
runs-on: ubuntu-latest
90+
steps:
91+
- name: Deploy application
92+
run: ./deploy.sh
93+
```
94+
95+
## Environment-Specific Keys
96+
97+
For different environments (staging vs production):
98+
99+
```json
100+
// key-manager.config.json
101+
{
102+
"requiredKeys": [
103+
{
104+
"name": "DATABASE_URL",
105+
"description": "PostgreSQL database connection string",
106+
"required": true,
107+
"inject": [".env"]
108+
},
109+
{
110+
"name": "STAGING_DATABASE_URL",
111+
"description": "Staging database connection string",
112+
"required": false,
113+
"inject": [".env.staging"]
114+
},
115+
{
116+
"name": "PROD_DATABASE_URL",
117+
"description": "Production database connection string",
118+
"required": false,
119+
"inject": [".env.production"]
120+
}
121+
]
122+
}
123+
```
124+
125+
Then in the workflow:
126+
127+
```yaml
128+
jobs:
129+
deploy-staging:
130+
if: github.ref == 'refs/heads/staging'
131+
uses: ./.github/workflows/key-manager.yml
132+
secrets: inherit
133+
with:
134+
command: 'scan'
135+
# Will check for STAGING_DATABASE_URL
136+
137+
deploy-production:
138+
if: github.ref == 'refs/heads/main'
139+
uses: ./.github/workflows/key-manager.yml
140+
secrets: inherit
141+
with:
142+
command: 'scan'
143+
# Will check for PROD_DATABASE_URL
144+
```
145+
146+
## Docker Build Integration
147+
148+
Inject keys before building Docker images:
149+
150+
```yaml
151+
jobs:
152+
prepare-keys:
153+
uses: ./.github/workflows/key-manager.yml
154+
secrets: inherit
155+
with:
156+
command: 'inject'
157+
158+
build-docker:
159+
needs: prepare-keys
160+
runs-on: ubuntu-latest
161+
steps:
162+
- uses: actions/checkout@v4
163+
164+
# Keys are now available in .env
165+
- name: Build Docker image
166+
run: |
167+
docker build \
168+
--build-arg DATABASE_URL=${{ secrets.DATABASE_URL }} \
169+
--build-arg ENCRYPTION_KEY=${{ secrets.ENCRYPTION_KEY }} \
170+
-t myapp:latest .
171+
```
172+
173+
## Complete Example
174+
175+
Here's a complete workflow showing all pieces together:
176+
177+
```yaml
178+
name: Complete CI/CD with Key Management
179+
180+
on:
181+
push:
182+
branches: [main, staging]
183+
pull_request:
184+
branches: [main]
185+
186+
jobs:
187+
# 1. Test and build
188+
test:
189+
runs-on: ubuntu-latest
190+
steps:
191+
- uses: actions/checkout@v4
192+
- name: Run tests
193+
run: npm test
194+
195+
# 2. Manage keys (only on push to main/staging)
196+
manage-keys:
197+
needs: test
198+
if: github.event_name == 'push'
199+
uses: ./.github/workflows/key-manager.yml
200+
secrets: inherit
201+
with:
202+
command: 'scan'
203+
dry_run: false
204+
205+
# 3. Build (depends on keys being ready)
206+
build:
207+
needs: [test, manage-keys]
208+
if: github.event_name == 'push'
209+
runs-on: ubuntu-latest
210+
steps:
211+
- uses: actions/checkout@v4
212+
- name: Build application
213+
env:
214+
DATABASE_URL: ${{ secrets.DATABASE_URL }}
215+
ENCRYPTION_KEY: ${{ secrets.ENCRYPTION_KEY }}
216+
run: npm run build
217+
218+
# 4. Deploy (only on main)
219+
deploy:
220+
needs: build
221+
if: github.ref == 'refs/heads/main'
222+
runs-on: ubuntu-latest
223+
steps:
224+
- uses: actions/checkout@v4
225+
- name: Deploy to production
226+
run: ./deploy.sh
227+
```
228+
229+
## Local Development Setup
230+
231+
For developers working locally:
232+
233+
```bash
234+
# 1. Install dependencies
235+
cd scripts
236+
npm install
237+
238+
# 2. Set up authentication
239+
export GITHUB_TOKEN="your_github_personal_access_token"
240+
export GITHUB_REPOSITORY="al7566/sim"
241+
242+
# 3. Check current keys
243+
bunx tsx key-manager.ts check
244+
245+
# 4. Inject keys from environment (for local .env)
246+
export DATABASE_URL="postgresql://localhost:5432/simstudio"
247+
export ENCRYPTION_KEY="$(openssl rand -hex 32)"
248+
export BETTER_AUTH_SECRET="$(openssl rand -hex 32)"
249+
bunx tsx key-manager.ts inject
250+
```
251+
252+
## Monitoring and Alerts
253+
254+
Set up notifications for key management:
255+
256+
```yaml
257+
jobs:
258+
manage-keys:
259+
uses: ./.github/workflows/key-manager.yml
260+
secrets: inherit
261+
with:
262+
command: 'scan'
263+
264+
notify:
265+
needs: manage-keys
266+
if: failure()
267+
runs-on: ubuntu-latest
268+
steps:
269+
- name: Send notification
270+
run: |
271+
echo "Key management failed!" | \
272+
curl -X POST ${{ secrets.SLACK_WEBHOOK }} \
273+
-H 'Content-Type: application/json' \
274+
-d '{"text":"Key management workflow failed"}'
275+
```
276+
277+
## Security Considerations
278+
279+
1. **Branch Protection**: Enable branch protection for main/staging
280+
2. **Required Reviews**: Require reviews for workflow changes
281+
3. **CODEOWNERS**: Add `.github/workflows/` to CODEOWNERS
282+
4. **Audit Logs**: Review GitHub audit logs regularly
283+
5. **Rotate Keys**: Set up calendar reminders for key rotation
284+
285+
## Rollback Plan
286+
287+
If key management causes issues:
288+
289+
```yaml
290+
# Temporarily disable by setting dry_run: true
291+
jobs:
292+
manage-keys:
293+
uses: ./.github/workflows/key-manager.yml
294+
secrets: inherit
295+
with:
296+
command: 'check'
297+
dry_run: true # Just check, don't modify
298+
```
299+
300+
Or comment out the key management job entirely while you investigate.
301+
302+
## Testing the Integration
303+
304+
1. **Test in a fork first**:
305+
```bash
306+
# Fork the repository
307+
# Add required secrets to fork
308+
# Test workflow runs
309+
```
310+
311+
2. **Use dry-run mode**:
312+
```yaml
313+
with:
314+
dry_run: true # Test without making changes
315+
```
316+
317+
3. **Start with `check` command**:
318+
```yaml
319+
with:
320+
command: 'check' # Just audit, don't modify
321+
```
322+
323+
4. **Monitor workflow runs**:
324+
- Check Actions tab
325+
- Review workflow logs
326+
- Verify no sensitive data exposed
327+
328+
## Troubleshooting
329+
330+
### Keys not being found
331+
- Verify secrets are added to repository settings
332+
- Check secret names match configuration
333+
- Ensure proper permissions on workflow
334+
335+
### Workflow fails
336+
- Check workflow logs for errors
337+
- Verify GitHub token has required permissions
338+
- Test locally with same commands
339+
340+
### Keys not injected
341+
- Check file paths in configuration
342+
- Verify injection targets exist
343+
- Review workflow artifacts
344+
345+
## Next Steps
346+
347+
After successful integration:
348+
349+
1. ✅ Set up weekly key audits
350+
2. ✅ Document key rotation schedule
351+
3. ✅ Add keys to .env.example with dummy values
352+
4. ✅ Train team on key management workflow
353+
5. ✅ Set up monitoring and alerts
354+
355+
## Resources
356+
357+
- [GitHub Actions Documentation](https://docs.github.com/en/actions)
358+
- [GitHub Secrets Management](https://docs.github.com/en/actions/security-guides/encrypted-secrets)
359+
- [Key Management Documentation](KEY_MANAGEMENT.md)
360+
- [Quick Start Guide](KEY_MANAGEMENT_QUICKSTART.md)

0 commit comments

Comments
 (0)