Reusable Workflows

The devex-reusable-workflows repository provides a library of GitHub Actions reusable workflows and composite actions used across all Foundations repositories for CI/CD.

Repository: badal-io/devex-reusable-workflows

Reusable Workflows

14 reusable workflows are available under .github/workflows/:

Workflow	Purpose	Version
`terraform-pr.yml`	Terraform plan on pull requests (mock credentials)	v0.x
`terraform-ci.yml`	Terraform apply on merge to main/env branches (real credentials)	v0.3.0
`docker-pr.yml`	Docker build and test on pull requests	v0.x
`docker-ci.yml`	Docker build and promote on merge	v0.x
`docker-release.yml`	Docker publish release images	v0.x
`semantic-release.yml`	Automated semantic versioning and release	v0.x
`generate-backends.yml`	Generate Terraform backend configurations	v0.x
`make.yml`	Run Makefile targets	v0.x
`tfc-apply.yml`	Terraform Cloud apply workflow	v0.x
`tfc-plan.yml`	Terraform Cloud plan workflow	v0.x
`release-please.yml`	Google release-please for changelog generation	v0.x
`release-please-pr.yml`	Create release-please pull requests	v0.x
`release-publish.yml`	Publish release artifacts	v0.x
`backstage-notify.yml`	Notify Backstage of pipeline status	v0.x

How to Reference Workflows

Call a reusable workflow from any repository using the standard GitHub Actions uses syntax:

jobs:
  terraform-plan:
    uses: badal-io/devex-reusable-workflows/.github/workflows/terraform-pr.yml@workflows/terraform-pr/v0.3.0
    with:
      working_directory: terraform/
    secrets: inherit

The @ reference uses the versioning tag format described in Versioning Scheme.

Composite Actions

22+ composite actions are organized by category:

Docker Actions (`actions/docker/`)

Action	Purpose
`build`	Build Docker images with caching
`push`	Push images to a container registry
`promote`	Promote images between registries/tags
`scan`	Scan images for vulnerabilities

GitHub Actions (`actions/github/`)

Action	Purpose
`create-pr`	Create pull requests programmatically
`comment-pr`	Add comments to pull requests
`notify`	Send notifications (Backstage, Slack)
`setup-git`	Configure git identity for CI commits

Terraform Actions (`actions/terraform/`)

Action	Purpose
`setup`	Install and configure Terraform CLI
`init`	Run `terraform init` with backend config
`plan`	Run `terraform plan` with output formatting
`apply`	Run `terraform apply` with safety checks
`fmt-check`	Check Terraform formatting
`validate`	Run `terraform validate`
`mock-credentials`	Generate mock GCP credentials for PR plans

Release-Please Actions (`actions/release-please/`)

Action	Purpose
`setup`	Configure release-please
`create-release`	Create GitHub releases with changelogs
`bump-version`	Determine next version from commits

Terraform Workflow Pattern

Terraform CI/CD follows a two-phase pattern that separates planning from applying:

PR Phase (terraform-pr)

Pull Request opened/updated
  └── terraform-pr workflow
      ├── terraform init
      ├── terraform fmt -check
      ├── terraform validate
      ├── Mock GCP credentials (WIF with limited permissions)
      ├── terraform plan
      └── Post plan output as PR comment

Uses mock credentials generated via the mock-credentials composite action
Plans are informational only; no changes are applied
Plan output is posted as a PR comment for review
Runs on every push to the PR branch

CI Phase (terraform-ci)

Merge to main (or env branch)
  └── terraform-ci workflow
      ├── terraform init
      ├── Authenticate via WIF (real credentials)
      ├── terraform plan
      ├── terraform apply -auto-approve
      └── Notify Backstage of completion

Uses real credentials via Workload Identity Federation
Applies changes automatically after merge
For environment-based branching, each branch triggers apply to its corresponding environment

Environment Mapping

Branching Model	Branch	Environment
Trunk-based	`main`	All environments (sequentially or parallel)
Environment-based	`development`	development
Environment-based	`non-production`	non-production
Environment-based	`production`	production

Docker Workflow Pattern

Docker CI/CD follows a three-phase pattern:

PR Phase (docker-pr)

Pull Request
  └── docker-pr workflow
      ├── Docker build (no push)
      ├── Run tests in container
      └── Vulnerability scan

CI Phase (docker-ci)

Merge to main
  └── docker-ci workflow
      ├── Docker build
      ├── Push to dev/staging registry
      └── Promote tag (if configured)

Release Phase (docker-release)

GitHub Release created
  └── docker-release workflow
      ├── Docker build with release tag
      ├── Push to production registry
      └── Sign image (if configured)

Release Management

Two release strategies are supported:

semantic-release

Uses semantic-release for automated versioning based on conventional commits:

fix: commits trigger patch releases
feat: commits trigger minor releases
BREAKING CHANGE triggers major releases
Automatically generates changelogs and GitHub releases

release-please

Uses Google's release-please for release management:

Creates and maintains release PRs with changelogs
Merging the release PR triggers the actual release
Supports monorepo configurations with per-path releases

Versioning Scheme

Workflows and actions use independent semantic versioning with path-based tags:

{type}/{path}/v{major}.{minor}.{patch}

Examples:

Tag	Description
`workflows/terraform-ci/v0.3.0`	Terraform CI workflow version 0.3.0
`workflows/docker-pr/v0.1.0`	Docker PR workflow version 0.1.0
`actions/terraform/plan/v1.0.0`	Terraform plan action version 1.0.0

This allows each workflow and action to be versioned independently. Consumers pin to specific versions and upgrade deliberately.

Design Principles

The reusable workflow library follows these principles:

Separation of concerns: Workflows handle orchestration; composite actions handle individual steps. This allows mixing and matching actions across workflows.
Credential isolation: PR workflows never receive real cloud credentials. Mock credentials allow terraform plan to succeed syntactically without granting any actual access.
Version independence: Each workflow and action is versioned separately. A breaking change in one workflow does not force upgrades of others.
Convention over configuration: Workflows assume standard directory layouts (terraform/, Dockerfile) and naming conventions. Overrides are available via input parameters.
Transparency: All plan outputs, build logs, and scan results are posted as PR comments for review before merge.
Composability: Workflows can be combined. For example, a repository might use terraform-pr + terraform-ci for infrastructure and docker-pr + docker-ci + docker-release for application code, all in the same repo.