afx-cicd-scaffold

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

1. Confirm the target project directory.
2. Preview with --dry-run:

   ~/.claude/skills/afx-cicd-scaffold/afx-cicd-scaffold.sh init /path/to/project --dry-run
   

3. Show the user what would be generated.
4. 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
   

5. 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)