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 Bastion bootstrap in tools. Container images are then re-tagged with the semver version. Once the Bastion + jumpbox are up, it applies infrastructure to test through the Bastion 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 Bastion + jumpbox via bcgov action)
                        ├─ .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 Bastion + jumpbox (tools) ──────────────────────────┤
                        └─ Apply to test (via Bastion tunnel)
                             └─ Integration tests (post-apply)
                                  ├─ Direct: pytest group=direct
                                  ├─ AI evaluation (optional, judge model configured)
                                  └─ Via proxy: pytest group=proxy (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 Bastion tunnel approach — for example, other repos without access to the tools Bastion — would still need self-hosted runners.

.deployer.yml (Reusable Workflow)

Reusable workflow (.Tools Environment Deployer) that provisions the shared tools environment in two ordered stages: (1) an initial-setup job runs the initial-setup/infra Terraform — resource group, spoke network wiring, and monitoring (Log Analytics workspace + Application Insights); (2) a bastion job provisions the Azure Bastion + jumpbox by calling the bcgov/action-deployer-vm-bastion-alz action (in the tools subscription), reusing the Log Analytics workspace from stage 1 as a bring-your-own workspace for Bastion diagnostics. It replaces the legacy proxy-based deploy. On destroy, the initial-setup stage is intentionally skipped so tearing down the Bastion stack does not remove the shared tools infrastructure.

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 ensures the tools Bastion is up, opens a Bastion SOCKS tunnel and starts 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 managing the tools Bastion + jumpbox stack on demand. It calls .deployer.yml (the bcgov action) to apply, plan, or destroy the stack.

Workflow Inputs

pr-open.yml (Pull Request Checks)

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

Bastion cost-saving (handled by the action's runbooks)

There is no longer a separate scheduled-cleanup workflow. Cost savings are built into the bcgov/action-deployer-vm-bastion-alz action via Azure Automation runbooks (enabled by enable_bastion_automation: "true"):

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