vk gha

Usage

vk gha bootstrap [options]   # OIDC provider + IAM deploy role
vk gha workflow  [options]   # .github/workflows/deploy.yml
vk gha e2e       [options]   # .github/workflows/e2e.yml

vk gha absorbs the “30 lines of AWS CLI plus hand-rolled JSON” that most projects paste into a DEPLOYMENT.md to get GitHub Actions deploying with short-lived OIDC credentials instead of long-lived access keys.

Subcommands

vk gha bootstrap

Auto-detects the GitHub repository from git remote origin and the deployable stages from vk.config.ts envs, then idempotently provisions:

• a single account-wide OpenID Connect provider for token.actions.githubusercontent.com (audience sts.amazonaws.com), and
• an IAM role whose trust policy accepts tokens minted by this repo for each declared stage — both the ref:refs/heads/<stage> and the environment:<stage> subject forms.

The role gets AdministratorAccess by default (pragmatic) or a VentureKit-maintained scoped inline policy (venturekit-deploy-scoped) with --scoped. Flip between them freely — re-running tidies up the previous attachment. The command ends by printing the role ARN and asking you to store it as the AWS_DEPLOY_ROLE_ARN repository secret.

Option	Description	Default
--repo <owner/repo>	GitHub repository	detected from git remote origin
--role <name>	IAM role name	venturekit-gha-deploy
--stages <list>	Comma-separated stages to trust	detected from vk.config.ts; dev,prod if none
--region <region>	AWS region for the STS + IAM calls (IAM is global)	us-east-1
--admin	Attach AdministratorAccess	on
--scoped	Attach the scoped inline policy instead of AdministratorAccess	off

vk gha workflow

Writes a ready-to-commit deploy pipeline that:

• triggers on pushes to the branches you map to stages (main → the prod stage; every other stage maps to the branch of the same name),
• authenticates to AWS via OIDC using secrets.AWS_DEPLOY_ROLE_ARN — no long-lived keys,
• runs pnpm exec vk deploy --stage <stage> with a concurrency group scoped to the stage, so parallel pushes serialise instead of racing the CloudFormation stacks.

Option	Description	Default
-p, --path <file>	Output path	.github/workflows/deploy.yml
--branch <branch=stage...>	Explicit branch → stage mapping (repeatable)	identity mapping + main → prod stage
--prod-stage <name>	Stage the main branch maps to	prod
--force	Overwrite an existing workflow file	off

The command refuses to overwrite an existing file without --force and prints the effective branch → stage table so you can re-run with --branch <branch>=<stage> --force if it doesn’t match your flow.

vk gha e2e

Writes a Playwright end-to-end workflow that runs on every pull request (and on pushes to the given branches). It needs no AWS credentials: the GitHub-hosted ubuntu-latest runner ships with Docker, which vk dev uses to start Postgres / MinIO / cognito-local, and the Playwright webServer block scaffolded by vk generate e2e boots vk dev and gates the specs on the /_dev/health probe. Newer pushes cancel in-flight runs for the same ref, and the Playwright HTML report is uploaded as an artifact (7-day retention).

Option	Description	Default
-p, --path <file>	Output path	.github/workflows/e2e.yml
--branch <branch...>	Branches that also trigger E2E on push	main
--force	Overwrite an existing workflow file	off

Examples

# One-time, with AWS admin credentials in the shell
vk gha bootstrap                      # detects repo + stages, AdministratorAccess
vk gha bootstrap --scoped             # least-privilege inline policy instead

# Commit the pipelines
vk gha workflow                       # dev → dev, stage → stage, main → prod
vk gha workflow --branch develop=dev --branch main=prod --force
vk gha e2e --branch main --branch develop

Then add the printed role ARN as the AWS_DEPLOY_ROLE_ARN secret in Settings → Secrets and variables → Actions, and push.

Related

• Deployment guide — stages, presets, and what vk deploy provisions
• Testing guide — the Playwright setup the E2E workflow runs