| name | afx-cicd-scaffold |
| description | Bootstrap a complete .github/workflows/ set for a new project: CI (build/test/lint), CD (workflow_dispatch with env choice + OIDC + ECR), security-scan (gitleaks + dependency scan + CodeQL), and optional database-migration. Use this skill when the user wants to add GitHub Actions CI/CD to a project that does not already have it, or when they want to add missing workflows alongside existing ones. |
Artifex CI/CD Scaffold Skill
For Claude Code AI Assistant
This skill generates a production-ready .github/workflows/ set for a project, replicating the patterns used in zoe and xenia/pms. It auto-detects the project stack and produces correctly-wired workflow files with all required secrets and variables documented inline.
What this skill generates
| File | Purpose |
|---|
.github/workflows/ci.yml | Runs on PR open/sync: build, test, lint. Stack-aware. |
.github/workflows/cd.yml | Manual deploy via workflow_dispatch with environment choice (staging / prod). OIDC auth, ECR image build/push, ECS deploy. |
.github/workflows/security-scan.yml | GitLeaks secret scan + OWASP dependency check + CodeQL SAST. Scheduled daily + PR trigger. |
.github/workflows/database-migration.yml | Optional. Flyway migrations via Gradle. Validates on PR, deploys on workflow_dispatch. |
.gitleaks.toml | GitLeaks configuration (dropped at project root alongside .github/). |
Stack detection
The script scans the project root for these marker files:
| Marker | Detected stack |
|---|
gradlew or pom.xml | JVM/Gradle (default) |
package.json | Node.js |
Cargo.toml | Rust |
go.mod | Go |
If none is found, JVM/Gradle is used (the user's primary stack).
Key design decisions
- Manual deploy only.
cd.yml uses workflow_dispatch with an environment input — no auto-deploy on push to main. This is intentional and must not be changed.
- OIDC for AWS auth. No long-lived credentials. The required IAM role pattern is documented in the
cd.yml header as arn:aws:iam::<account>:role/<project>-gha-deploy-<env>.
- Concurrency group
deploy-${{ inputs.environment }} with cancel-in-progress: false. Prevents two prod deploys racing. This is the xenia/pms pattern.
--force required to overwrite. Existing files are never silently clobbered. New files are always added side-by-side.
Conversational Routing
| User phrasing | Action |
|---|
| "add CI/CD to my project", "scaffold GitHub Actions", "set up workflows" | Run init in the project directory |
| "add CI/CD without the database migration" | Run init --no-db-migration |
| "preview what would be created" | Run init --dry-run |
| "overwrite my existing workflows" | Run init --force |
| "add security scanning" | Run init — security-scan.yml is always included |
If the user is working in a specific project directory, use that directory as the target. If no project directory is given, default to the current working directory.
How to run this skill
Standard scaffolding
- Confirm the target project directory.
- Preview with
--dry-run:
~/.claude/skills/afx-cicd-scaffold/afx-cicd-scaffold.sh init /path/to/project --dry-run
- Show the user what would be generated.
- If they approve, run for real (with optional
--no-db-migration if they do not use a database):
~/.claude/skills/afx-cicd-scaffold/afx-cicd-scaffold.sh init /path/to/project
- Walk the user through the next steps printed by the script:
- Review and customise the generated files
- Set the secrets and variables listed in the file header comments
- Create the OIDC IAM roles for
cd.yml
- Commit the files
Adding workflows to an existing project
If .github/workflows/ already exists:
- New files (ones not already present) are added automatically without
--force.
- Existing files are skipped with a warning.
- If the user wants to regenerate all files from scratch, re-run with
--force.
Database migration workflow
When the script runs interactively, it prompts whether to include database-migration.yml. The user can suppress the prompt with --no-db-migration. If the session is non-interactive (piped), the migration file is skipped by default.
Required secrets and variables reference
All are documented inline in the generated file headers. Key ones for cd.yml:
| Name | Type | Description |
|---|
AWS_ROLE_ARN_STAGING | Secret | OIDC role ARN for staging: arn:aws:iam::<acct>:role/<project>-gha-deploy-staging |
AWS_ROLE_ARN_PROD | Secret | OIDC role ARN for production: arn:aws:iam::<acct>:role/<project>-gha-deploy-prod |
STAGING_URL | Secret | Base URL for staging smoke tests |
PROD_URL | Secret | Base URL for production smoke tests |
AWS_REGION | Variable | AWS region (e.g. us-east-1) |
ECR_REPOSITORY | Variable | ECR repository name |
ECS_SERVICE | Variable | ECS service name |
ECS_CLUSTER_STAGING | Variable | ECS cluster name for staging |
ECS_CLUSTER_PROD | Variable | ECS cluster name for production |
Version
1.0.0 (ticket 12.2)
