GitHub Actions Automation Workflows

This page explains the GitHub Actions workflows used by the repository. These workflows build containers, validate infrastructure changes, and deploy platform resources by using passwordless sign-in to Azure through OpenID Connect.

Workflow Overview

Tenant Onboarding Portal Workflows

The tenant onboarding portal now keeps Terraform in tenant-onboarding-portal/infra while the application code lives under tenant-onboarding-portal/backend and tenant-onboarding-portal/frontend. GitHub Actions provisions App Service from the root infra/ folder, builds the frontend separately, copies the SPA into the backend deployment bundle, and deploys the backend package to App Service via zip deployment.

Developer SDLC Flow (Branch → PR → TEST → PROD)

The repository enforces a promote-through-environments workflow. Every change flows through a validated path before reaching production.

1. Create feature branch from main (e.g. feat/<work-item>, fix/<issue>) and commit changes.
2. Open PR to main, which triggers pr-open.yml:
   • Lint (pre-commit: terraform fmt + tflint, conventional commit title, fork check)
   • Container image builds
   • Terraform plan against test (via secure tunnel) — summary appended to PR description
3. Merge to main once PR checks and code review pass.
4. Auto-apply to test + semver tag: merge-main.yml starts two jobs concurrently — semantic versioning (conventional commit history → v1.2.3 tag + CHANGELOG.md update) and proxy bootstrap in tools. Container images are then re-tagged with the semver version. Once the proxy is up, it applies infrastructure to test through the Chisel tunnel. After a successful apply, integration tests run automatically (two phases — see below).
5. Promote to prod: Use manual-dispatch.yml, select prod + apply, and provide the semver tag. The workflow verifies all container images exist with that tag, then deploys using the semver-tagged images (not latest). This is gated — requires approval from designated reviewers (configured in the GitHub prod environment protection rules).
6. Release created: After successful prod apply, a GitHub Release is automatically created from the deployed tag with deployment metadata.

Feature Branch
   │
   └── Pull Request ──► pr-open.yml
                        ├─ .lint.yml (fmt, tflint, conventional commits, fork check)
                        ├─ .builds.yml
                        ├─ .deployer.yml (tools/azure_proxy)
                        ├─ .deployer-using-secure-tunnel.yml (test plan)
                        └─ Update PR description with plan summary
                                  │
                                  ▼
                             Merge to main
                                  │
                                  ▼
                        merge-main.yml
                        ├─ Semantic version tag (v1.2.3) ─────────────────── concurrent
                        ├─ Tag container images (latest → v1.2.3) ──────── after semver
                        ├─ Deploy azure_proxy (tools) ───────────────────────────────┤
                        └─ Apply to test (via Chisel tunnel)
                             └─ Integration tests (post-apply)
                                  ├─ Direct: all tests except apim-key-rotation.bats
                                  └─ Via proxy: apim-key-rotation.bats (KV private endpoint)
                                  │
                                  ▼
                        manual-dispatch.yml (prod + apply + tag)
                        ├─ ⏸ Requires prod environment approval
                        ├─ Verify container images exist for semver tag
                        ├─ Apply to prod using semver-tagged images
                        └─ Create GitHub Release

Advanced Branching Patterns

The basic SDLC flow above covers the single-feature-per-PR path. In practice, teams often need to coordinate dependent work or bundle multiple features into a single release. Two patterns handle this: Stacked PRs and Release PRs.

Stacked PRs (Dependent Feature Chains)

Use stacked PRs when a feature depends on another feature that hasn't merged to main yet. Each PR in the stack targets the previous branch instead of main.

main ─────────────────────────┬───────────────────┬──────►
   \                          │ merge PR #1        │ merge PR #2
    └─ feat/base-network ─────┘   (v1.3.0)        │
         \                                         │
          └─ feat/add-apim-policy ─── rebase ──────┘
                                                 (v1.4.0)

Release PRs (Bundled Multi-Feature Releases)

Use a Release PR when multiple developers are working on separate features that should ship together as a single coordinated release. All feature branches merge into a shared release branch, which then opens one PR to main.

main ─────────────────────────────────────────┬──────────►
   \                                           │ merge Release PR
    └─ release/sprint-42 ───┬──────┬──────────┘  (v2.0.0)
         \                  │      │
          ├─ feat/tenant ───┘      │
          │                        │
          └─ feat/rate-limits ─────┘

Choosing Between Stacked PRs and Release PRs

When Do I Need Self-Hosted Runners?

The table below describes the general pattern. Data-plane work that can't use the Chisel tunnel approach — for example, other repos without the proxy setup — would still need self-hosted runners.

.deployer.yml (Reusable Workflow)

Reusable Terraform workflow for initial-setup/infra, primarily used to manage the tools environment and targeted foundational modules.

Required Permissions

permissions:
  id-token: write   # Required for OIDC token generation
  contents: read    # Required for repository checkout

.deployer-using-secure-tunnel.yml (Reusable Workflow)

Reusable Terraform workflow for infra-ai-hub. It receives encrypted proxy outputs from .deployer.yml, starts Chisel + Privoxy, then runs stack deployment and (for apply in dev/test) integration tests.

.lint.yml (Reusable Workflow)

Reusable validation workflow used by PR checks. Runs Terraform formatting and linting, enforces PR title conventions, and blocks forks.

.builds.yml (Container Build Workflow)

Reusable workflow for building and pushing container images to GitHub Container Registry (GHCR). Supports matrix builds for multiple packages including the azure-proxy services.

add-or-remove-module.yml

Manual workflow for deploying or destroying infrastructure modules on demand. Evolved from the earlier bastion-only workflow to support all optional modules (bastion, jumpbox, azure_proxy, github_runners_aca).

Workflow Inputs

pr-open.yml (Pull Request Checks)

Runs on pull request events (and manual dispatch) to provide fast CI signal before merge.

schedule.yml (Scheduled Cleanup)

Automatically destroys Bastion every day at 5 PM PST to prevent unnecessary charges.

# Runs daily at 5 PM PST (1 AM UTC next day)
on:
  schedule:
    - cron: "0 1 * * *"

Jobs Flow

check-and-destroy-bastion
         │
         ├── bastion_exists=true ──► destroy-bastion ──► notification
         │
         └── bastion_exists=false ──────────────────────► notification

manual-dispatch.yml (Manual Promotion Workflow)

Use this workflow to run plan, apply, or destroy for dev, test, and prod.

merge-main.yml (Auto Apply + Semantic Version on Main)

This workflow runs on every push to main. It creates a semantic version tag using Conventional Commits and then applies infrastructure to test.

Release Process (TEST → PROD)

Production releases follow a tag-based promotion flow:

Concurrency Strategy

Several workflows and reusable jobs use concurrency to prevent race conditions and conflicting Terraform operations.

APIM Key Rotation

APIM subscription key rotation is now handled by a Container App Job (scheduled) deployed as a custom container. The job source is at jobs/apim-key-rotation/ and the Terraform module at infra-ai-hub/modules/key-rotation-function/.

pages.yml (Documentation)

Deploys this documentation site to GitHub Pages when changes are pushed to docs or Terraform roots (so generated references stay current).

Environment Secrets

Each GitHub environment requires these secrets (created by initial-azure-setup.sh):

Subnet Allocation Process (Blob First)

For visibility and team collaboration, keep network JSON in Azure Blob first, then copy the same JSON into GitHub environment secrets.

1. Update the environment file in Blob storage (for example, subnet-allocation-dev.json or subnet-allocation-test.json in network-info/subnet-allocation).
2. Copy the JSON payload and paste it into the matching GitHub environment secret SUBNET_ALLOCATION.
3. If direct APIM access from peered VNets is needed, copy the external_peered_projects JSON payload into optional secret EXTERNAL_PEERED_PROJECTS.
4. Run plan in that environment to validate before apply.

How JSON Flows into Terraform

1. GitHub Actions reads secrets.SUBNET_ALLOCATION.
2. The reusable workflow maps it to TF_VAR_subnet_allocation.
3. Terraform parses the JSON into var.subnet_allocation (map(map(string))).
4. If secrets.EXTERNAL_PEERED_PROJECTS is present, the workflow exports it as TF_VAR_external_peered_projects and Terraform parses it into var.external_peered_projects.

Common Errors You Might See

• Missing secret: Error: Required environment secret SUBNET_ALLOCATION is missing or empty.
• Invalid JSON: Error: SUBNET_ALLOCATION must be valid JSON and a non-empty JSON object.
• Invalid optional peered-project JSON: workflow JSON parse step fails when EXTERNAL_PEERED_PROJECTS is not a valid JSON object.
• Type/shape mismatch in Terraform: validation errors from variable "subnet_allocation" (invalid CIDR, duplicate subnet names, missing PE subnet, unsupported subnet key).
• Peered-project validation errors: Terraform errors for external_peered_projects (invalid CIDR, priority outside 400–499, duplicate priority, invalid project name format).
• Wrong precedence assumptions: values in -var-file override TF_VAR_*; keep subnet_allocation out of committed shared.tfvars.

Running Workflows Locally

For local development and testing, use the deployment scripts in each Terraform root:

# Load required subnet allocation JSON (example: prod)
az account set --subscription "da4cf6-tools - AI Services Hub"
tmpfile=$(mktemp)
az storage blob download \
    --account-name tftoolsaihubtracking \
    --container-name tools \
    --name network-info/subnet-allocation/subnet-allocation-prod.json \
    --auth-mode login \
    --file "$tmpfile"
export TF_VAR_subnet_allocation="$(jq -c . "$tmpfile")"
rm -f "$tmpfile"

# Switch back to your deployment subscription before running terraform
az account set --subscription "da4cf6-dev - AI Services Hub"

# Ensure you're logged in
az login

# Initial setup / tools
./initial-setup/infra/deploy-terraform.sh init
./initial-setup/infra/deploy-terraform.sh plan
./initial-setup/infra/deploy-terraform.sh apply

# AI Hub stacks
./infra-ai-hub/scripts/deploy-terraform.sh plan dev
./infra-ai-hub/scripts/deploy-terraform.sh apply test