CI/CD Pipeline

GitLab CI/CD drives validation, testing, and deployment for the Goosehead Fastlane monorepo. The promotion lane builds the core apps once, promotes them through five environments with manual approval gates, and now sits alongside a release lane for lower-environment release/* deploys from GitLab Run pipeline.

Environment Promotion Model

Hotfixes bypass the promotion chain entirely:

Pipeline Modes

MR Pipeline

Runs on every merge request. Validates code quality, security, builds, and test coverage before merge.

See MR Pipeline for details.

Deploy Pipeline

Runs in two modes:

• Promotion lane: push to develop, then promote through dev -> qa -> uat -> staging -> prod
• Release lane: GitLab Run pipeline on release/* with manual target_env inputs. See Manual Pipeline Inputs for the current option contract and rollout notes.

See Deployment for details.

Deployable Apps

App	Path	Dockerfile	Runtime
fastlane-portal	apps/fastlane-portal	apps/fastlane-portal/Dockerfile	nginx:alpine
fastlane-admin	apps/fastlane-admin	apps/fastlane-admin/Dockerfile	nginx:alpine
fastlane-api-gateway	apps/apis/fastlane-api-gateway	apps/apis/fastlane-api-gateway/Dockerfile	node:22-alpine
docs	apps/docs	apps/docs/Dockerfile	nginx:alpine
components (Storybook)	libs/ui/components	libs/ui/components/Dockerfile	nginx:alpine

Key Files

File	Purpose
.gitlab-ci.yml	Main pipeline definition (stages, jobs, templates, deploy matrices)
ci/scripts/promote-image.sh	Pull from GitLab CR, retag for Heroku, push, release, health check
ci/scripts/deploy-app.sh	Legacy Docker build + push (retained for reference)
ci/scripts/claude-mr-review.sh	AI code review (code quality + security) posted as MR notes
ci/app-to-heroku-mapping.json	Reference mapping of apps to Heroku app names per environment

Pipeline Stages

Stage	When	Purpose
detect	develop / main push	Rebuild .env.vault from dotenv.org
validate	MR	Lint, Trivy SCA, Trivy IaC
build	MR	Parallel NX build of all 5 apps
test	MR	Coverage + Claude AI review
build-images	develop / main push	Build Docker images, push to GitLab Container Registry
deploy-dev	develop push	Promote pre-built images to dev Heroku apps
verify-dev	develop push	E2E tests, database migrations, seed
deploy-qa	manual	Deploy to QA with approval
verify-qa	after QA deploy	E2E tests against QA
deploy-uat	manual	Deploy to UAT with approval
verify-uat	after UAT deploy	Manual release-lane migration job for UAT, when requested
deploy-staging	manual	Deploy to staging with approval
deploy-prod	manual	Deploy to production with approval
post-deploy	after prod deploy	Sync develop to main / hotfix backport

Documentation

• How to Deploy -- end-to-end deployment guide, dotenv-vault secrets, GitLab setup
• Manual Pipeline Inputs -- GitLab Run pipeline input options, guardrails, UI steps, and rollout notes
• Updating Environment Variables -- managing local .env, dotenv.org dashboard, access control, CI auto-build
• Secrets Vault -- how dotenv-vault works, split-knowledge encryption, CI auto-build, security model
• MR Pipeline -- lint, security scans, builds, tests, AI review
• Deployment -- environment promotion, deploy scripts
• Environments -- env details, Heroku mappings, CI variables
• Docker Builds -- frontend vs backend containerization patterns
• Fast Prod Deploy -- skip the env chain, deploy directly to production
• Hotfix Flow -- main-branch hotfix + auto-backport workflow