GitHub Actions Deployment

Backend build, test, and deployment live in .github/workflows/backend.yml. Frontend build, typecheck, and deployment live in .github/workflows/frontend.yml. MCP server build and deployment live in .github/workflows/mcp.yml. Docs build and deployment live in .github/workflows/docs.yml.

Pull request validation lives in the surface workflows:

• .github/workflows/backend.yml
• .github/workflows/frontend.yml
• .github/workflows/docs.yml
• .github/workflows/mcp.yml
• .github/workflows/pipelines.yml
• .github/workflows/chrome-extension.yml
• .github/workflows/agent-hooks.yml

On pushes to staging or prod, the backend workflow deploys the matching GitHub environment:

• Builds backend/ as a Docker image and pushes it to Amazon ECR.
• Starts a new ECS service deployment after the image is pushed.

On pushes to staging or prod, the frontend workflow deploys the matching environment by building frontend/portal, uploading the static assets to the Terraform-managed S3 frontend bucket, and invalidating the CloudFront distribution.

On pushes to staging or prod, the docs workflow deploys the matching environment by building docs/app/, uploading the static assets to the Terraform-managed S3 docs bucket, and invalidating the docs CloudFront distribution.

• staging builds with DOCS_ENV=staging, which publishes public and internal docs to https://staging-docs.olivergraph.com with noindex.
• prod builds with DOCS_ENV=production, which publishes public docs only to https://docs.olivergraph.com.

GitHub Setup

The deploy jobs use GitHub environments named staging and production. Add these variables in Settings > Environments > <environment> > Environment variables:

Name	Example	Notes
AWS_REGION	us-east-1	Terraform region.
AWS_ROLE_ARN	<github_deploy_role_arns[env]>	Deploy role created by Terraform.
ECR_REPOSITORY	context-layer-staging-backend	Backend ECR repository name.
MCP_ECR_REPOSITORY	oliver-mcp-staging	MCP ECR repository name.
ECS_CLUSTER	context-layer	Terraform ECS cluster name.
ECS_SERVICE	context-layer-staging-backend	Backend ECS service name.
MCP_ECS_SERVICE	oliver-mcp-staging	MCP ECS service name.
BACKEND_API_URL	https://staging-api.olivergraph.com	API URL used by the frontend build. Use https://api.olivergraph.com for production.
FRONTEND_S3_BUCKET	oliver-context-layer-staging-frontend-361357547262	Frontend bucket from terraform output -json frontend_buckets.
CLOUDFRONT_DISTRIBUTION_ID	E3N9NP2AUPDO9I	CloudFront distribution from terraform output -json frontend_cloudfront_distribution_ids.
DOCS_S3_BUCKET	oliver-context-layer-staging-docs-361357547262	Docs bucket from terraform output -json docs_buckets.
DOCS_CLOUDFRONT_DISTRIBUTION_ID	E123EXAMPLE	Docs CloudFront distribution from terraform output -json docs_cloudfront_distribution_ids.
SUPABASE_URL	https://aglslorvlcoelvgymfvb.supabase.co	Public Supabase URL used by the frontend build.
SUPABASE_PUBLISHABLE_KEY	sb_publishable_...	Public Supabase publishable key used by the frontend build.

Production deploys should be a separate promotion path. Do not point the staging environment variables at prod resources.

AWS IAM

Use a GitHub OIDC role whose trust policy allows this repository to assume it from the selected GitHub deployment environment. The role needs permissions for backend and MCP deploys:

• ecr:GetAuthorizationToken
• ecr:BatchCheckLayerAvailability
• ecr:InitiateLayerUpload
• ecr:UploadLayerPart
• ecr:CompleteLayerUpload
• ecr:PutImage
• ecs:UpdateService

And for frontend and docs deploys:

• s3:ListBucket
• s3:GetObject
• s3:PutObject
• s3:DeleteObject
• cloudfront:CreateInvalidation

The Terraform stack in infra/aws creates the ECR repositories, ECS services, frontend/docs S3 buckets, CloudFront distributions, deploy roles, and shared database/auth infrastructure that the workflows expect.

Manual Deploy

You can also run the workflow manually from the Actions tab with workflow_dispatch.