22
33This directory contains automated workflows for the Ambient Code Platform.
44
5- ## Active Workflows
5+ For a complete inventory of workflows, read the ` name: ` field in each
6+ ` .yml ` /` .yaml ` file in this directory. Do not rely on a static list here —
7+ see [ #769 ] ( https://github.com/ambient-code/platform/issues/769 ) .
68
7- ### 🤖 Amber Issue-to-PR Handler ( ` amber-issue-handler.yml ` )
9+ ## Security
810
9- ** Purpose** : Automatically processes GitHub issues and creates pull requests using the Amber background agent.
10-
11- ** Triggers** :
12- - Issue labeled with ` amber:auto-fix ` , ` amber:refactor ` , or ` amber:test-coverage `
13- - Issue comment containing ` /amber execute `
14-
15- ** What It Does** :
16- 1 . Parses issue for file paths, instructions, and context
17- 2 . Executes Amber agent with appropriate prompt
18- 3 . Creates feature branch with fixes/refactoring/tests
19- 4 . Opens pull request with changes
20- 5 . Links PR back to original issue
21-
22- ** Requirements** :
23- - ` ANTHROPIC_API_KEY ` secret configured
24- - Workflow permissions: read/write for contents, issues, PRs
25-
26- ** Documentation** : [ Amber Automation Guide] ( ../../docs/amber-automation.md )
27-
28- ---
29-
30- ### 🏗️ Components Build & Deploy (` components-build-deploy.yml ` )
31-
32- ** Purpose** : Builds and deploys platform components on changes.
33-
34- ** Triggers** :
35- - Push to ` main ` branch
36- - Pull requests affecting component directories
37-
38- ** What It Does** :
39- 1 . Detects which components changed
40- 2 . Builds multi-platform Docker images (amd64, arm64)
41- 3 . Pushes to ` quay.io/ambient_code ` registry (main branch only)
42- 4 . Runs component-specific tests
43-
44- ** Change Detection** :
45- - Frontend: ` components/frontend/** `
46- - Backend: ` components/backend/** `
47- - Operator: ` components/operator/** `
48- - Claude Runner: ` components/runners/ambient-runner/** `
49-
50- ---
51-
52- ### 🧪 E2E Tests (` e2e.yml ` )
53-
54- ** Purpose** : Runs end-to-end tests in Kind (Kubernetes in Docker).
55-
56- ** Triggers** :
57- - Pull requests
58- - Manual workflow dispatch
59-
60- ** What It Does** :
61- 1 . Sets up Kind cluster
62- 2 . Deploys full vTeam stack
63- 3 . Runs Cypress tests against UI
64- 4 . Reports results
65-
66- ** Documentation** : [ E2E Testing Guide] ( ../../docs/testing/e2e-guide.md )
67-
68- ---
69-
70- ### 🔧 Test Local Dev (` test-local-dev.yml ` )
71-
72- ** Purpose** : Validates local development setup works correctly.
73-
74- ** Triggers** :
75- - Changes to dev scripts (` Makefile ` , ` dev-start.sh ` , etc.)
76- - Manual workflow dispatch
77-
78- ** What It Does** :
79- 1 . Simulates local development environment
80- 2 . Tests ` make dev-start ` , ` make dev-stop `
81- 3 . Verifies CRC integration
82-
83- ---
84-
85- ### 🔄 Dependabot Auto-Merge (` dependabot-auto-merge.yml ` )
86-
87- ** Purpose** : Automatically merges Dependabot dependency updates.
88-
89- ** Triggers** :
90- - Dependabot PR creation
91-
92- ** What It Does** :
93- 1 . Checks if PR is from Dependabot
94- 2 . Waits for CI to pass
95- 3 . Auto-merges patch/minor version updates
96- 4 . Requires manual review for major updates
97-
98- ---
99-
100- ### 📋 Project Automation (` project-automation.yml ` )
101-
102- ** Purpose** : Manages GitHub project board automation.
103-
104- ** Triggers** :
105- - Issue/PR status changes
106- - Label additions
107-
108- ** What It Does** :
109- - Moves issues between project columns
110- - Auto-assigns based on labels
111- - Updates project metadata
112-
113- ---
114-
115- ### 🤝 Claude Code Integration (` claude.yml ` )
116-
117- ** Purpose** : Integrates Claude Code with GitHub workflows.
118-
119- ** Triggers** :
120- - Push to branches
121- - PR creation/updates
122-
123- ** What It Does** :
124- - Enables Claude Code suggestions in PRs
125- - Provides AI-powered code review
126- - Links to Claude Code sessions
127-
128- ---
129-
130- ## Workflow Permissions
11+ ### Permissions
13112
13213All workflows follow ** principle of least privilege** :
13314
@@ -139,165 +20,57 @@ permissions:
13920 packages : write # Only for image publishing
14021` ` `
14122
142- ## Security Considerations
143-
144- ### Secrets Required
145-
146- | Secret | Used By | Purpose |
147- |--------|---------|---------|
148- | ` ANTHROPIC_API_KEY` | amber-issue-handler.yml | Claude API access |
149- | `GITHUB_TOKEN` | All workflows | GitHub API access (auto-provided) |
150-
15123### Command Injection Prevention
15224
153- All workflows use **environment variables** to pass user input (issue titles, bodies, comments) to prevent command injection attacks.
25+ Pass user input through environment variables, never through string
26+ interpolation in ` run:` blocks.
15427
155- **Example ( Safe)** :
28+ Safe :
15629` ` ` yaml
15730env:
15831 ISSUE_TITLE: ${{ github.event.issue.title }}
15932run: echo "$ISSUE_TITLE"
16033` ` `
16134
162- **Anti-Pattern ( Unsafe)** :
35+ Unsafe :
16336` ` ` yaml
164- run: echo "${{ github.event.issue.title }}" # ❌ Vulnerable to injection
37+ run: echo "${{ github.event.issue.title }}" # Vulnerable to injection
16538` ` `
16639
167- **Reference**: [GitHub Actions Security Guide](https://github.blog/security/vulnerability-research/how-to-catch-github-actions-workflow-injections-before-attackers-do/)
168-
169- ---
170-
171- # # Monitoring
40+ Reference : [GitHub Actions Security Guide](https://github.blog/security/vulnerability-research/how-to-catch-github-actions-workflow-injections-before-attackers-do/)
17241
173- # ## View All Workflow Runs
42+ # # Monitoring and Troubleshooting
17443
17544` ` ` bash
176- gh run list
45+ gh run list # All recent runs
46+ gh run list --workflow=e2e.yml # Runs for a specific workflow
47+ gh run watch # Watch a running workflow
48+ gh run view <run-id> --log # View logs
49+ gh run view <run-id> --log-failed # View only failure logs
50+ gh run rerun <run-id> --failed # Re-run failed jobs
17751` ` `
17852
179- # ## View Specific Workflow
180-
181- ` ` ` bash
182- gh run list --workflow=amber-issue-handler.yml
183- ` ` `
184-
185- # ## Watch Running Workflow
186-
187- ` ` ` bash
188- gh run watch
189- ` ` `
190-
191- # ## View Logs
192-
193- ` ` ` bash
194- gh run view <run-id> --log
195- ` ` `
196-
197- ---
198-
199- # # Troubleshooting
200-
201- # ## Workflow Not Triggering
202-
203- **Check**:
204- 1. Workflow file syntax : ` gh workflow list`
205- 2. Trigger conditions match event
206- 3. Workflow permissions enabled (Settings → Actions)
207-
208- **Debug**:
209- ` ` ` bash
210- # View workflow status
211- gh workflow view amber-issue-handler.yml
212-
213- # Check recent runs
214- gh run list --workflow=amber-issue-handler.yml --limit 5
215- ` ` `
216-
217- # ## Workflow Failing
218-
219- **Common Issues**:
220- 1. Missing secret (check Settings → Secrets)
221- 2. Insufficient permissions (check workflow `permissions:`)
222- 3. Syntax error in YAML (use `yamllint`)
223-
224- **Debug**:
225- ` ` ` bash
226- # View failure logs
227- gh run view <run-id> --log-failed
228-
229- # Re-run failed jobs
230- gh run rerun <run-id> --failed
231- ` ` `
232-
233- ---
234-
235- # # Adding New Workflows
236-
237- # ## Checklist
238-
239- - [ ] Define clear trigger conditions (`on:`)
240- - [ ] Set minimal permissions (`permissions:`)
241- - [ ] Use env vars for user input (prevent injection)
242- - [ ] Add documentation to this README
243- - [ ] Test in fork before merging
244- - [ ] Add workflow badge to main README (optional)
245-
246- # ## Template
247-
248- ` ` ` yaml
249- name: Your Workflow Name
250-
251- on:
252- # Define triggers
253- push:
254- branches: [main]
255-
256- permissions:
257- contents: read # Minimal permissions
258-
259- jobs:
260- your-job:
261- runs-on: ubuntu-latest
262- steps:
263- - uses: actions/checkout@v4
264- - name: Your step
265- env:
266- # Use env vars for user input
267- INPUT: ${{ github.event.inputs.value }}
268- run: |
269- echo "$INPUT"
270- ` ` `
271-
272- ---
273-
27453# # Best Practices
27554
276- # ## ✅ Do
55+ # ## Do
27756
27857- Use latest action versions (`actions/checkout@v4`)
27958- Set explicit permissions per workflow
28059- Pass user input via environment variables
28160- Cache dependencies (npm, pip, Go modules)
28261- Fail fast for critical errors
28362
284- # ## ❌ Don't
63+ # ## Don't
28564
28665- Use `permissions : write-all` (too broad)
28766- Interpolate user input directly in `run:` commands
28867- Hardcode secrets (use GitHub Secrets)
28968- Run workflows on every push (use path filters)
29069- Ignore security warnings from GitHub
29170
292- ---
293-
29471# # Related Documentation
29572
29673- [Amber Automation Guide](../../docs/amber-automation.md)
29774- [E2E Testing Guide](../../docs/testing/e2e-guide.md)
29875- [GitHub Actions Docs](https://docs.github.com/en/actions)
29976- [Security Best Practices](https://docs.github.com/en/actions/security-for-github-actions)
300-
301- ---
302-
303- **Questions?** Create an issue with label `workflow:help`
0 commit comments