GitHub Actions CI/CD Pipeline Templates: Reusable Workflows for Testing, Security, and Deployment

Overview

A GitHub Actions pipeline is easiest to maintain when each job has one clear responsibility and the workflow treats build outputs as versioned artifacts. A practical cloud-native pipeline commonly separates validation from packaging, security checks, and deployment:

1. Pull request validation: format, lint, unit test, and validate configuration before code can merge.
2. Build and package: create a repeatable application or container artifact once, rather than rebuilding different versions for each environment.
3. Security checks: inspect dependencies, source code, and container images according to the risks relevant to the project.
4. Promotion: move the same artifact through staging and production with explicit environment controls.
5. Deployment and verification: update the target platform, wait for the rollout, and expose enough logs for diagnosis.

This separation prevents a common failure mode: a workflow that appears to be one large deployment script but quietly mixes untrusted pull request code, credentials, build logic, and production access. Start with the smallest pipeline that gives useful feedback, then add controls as the release process becomes more mature.

For Kubernetes projects, the deployment job should complement—not replace—operational checks. If a rollout fails, use a focused Kubernetes deployment troubleshooting checklist. If the application emits telemetry during deployment, review the team’s approach to cloud observability tools and collection patterns.

Template structure

The following workflow is intentionally provider-neutral. It demonstrates job boundaries, permissions, caching, an artifact handoff, and a deployment placeholder without assuming a particular cloud or Kubernetes tool.

name: CI/CD

on:
  pull_request:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read

concurrency:
  group: ci-cd-${{ github.ref }}
  cancel-in-progress: true

jobs:
  test:
    name: Test (${{ matrix.version }})
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        version: ['20', '22']
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.version }}
          cache: npm
      - run: npm ci
      - run: npm run lint
      - run: npm test -- --ci

  security:
    name: Security checks
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm audit --audit-level=high
      # Add the source, dependency, or container scanner used by your team.

  package:
    name: Build artifact
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    needs: [test, security]
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
          cache: npm
      - run: npm ci
      - run: npm run build
      - uses: actions/upload-artifact@v4
        with:
          name: application-${{ github.sha }}
          path: dist/
          if-no-files-found: error

  deploy-staging:
    name: Deploy to staging
    needs: package
    runs-on: ubuntu-latest
    environment: staging
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: application-${{ github.sha }}
          path: dist/
      - run: ./scripts/deploy-staging.sh dist/

  deploy-production:
    name: Deploy to production
    needs: deploy-staging
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: application-${{ github.sha }}
          path: dist/
      - run: ./scripts/deploy-production.sh dist/

Replace the Node commands with the commands for the project. The important design choices are portable:

• Use needs to express promotion order. A production job should not run until its required checks and earlier environment have completed.
• Use a matrix selectively. Test the supported runtime versions, operating systems, or database versions that can reveal meaningful compatibility problems. Avoid expanding the matrix simply because it is easy to do so.
• Upload the build output once. Promotion from the same artifact makes the release easier to identify and reduces differences between staging and production.
• Use environments for controls. Environment protection rules can provide approvals and scoped variables where the repository’s governance requires them.
• Keep permissions narrow. Begin with read-only repository access and grant additional permissions only to the job that needs them.

How to customize

Pull request checks

Keep pull request workflows fast enough to run frequently. Run formatting, linting, unit tests, configuration validation, and lightweight dependency checks before merge. Expensive integration or end-to-end tests can run in a separate job when they require services or longer-lived infrastructure. Make required checks stable in name; changing job names frequently can create administrative work in branch protection settings.

Dependencies and caching

Prefer the package manager’s lockfile and clean installation mode. Caching should accelerate a reproducible install, not become a hidden source of state. If a dependency update changes the lockfile, the cache key should naturally change. When a cache causes confusing failures, temporarily disable it to distinguish cache problems from application problems.

Container builds and scanning

For containerized applications, add a build job that tags the image with an immutable identifier such as the commit SHA. Publish it to the registry selected by the team, then scan the image before promotion. Do not make a mutable tag such as latest the only reference used by deployment automation. A registry decision also affects authentication, retention, and pull access; compare those operational requirements before standardizing the workflow. The container registry comparison can help organize that evaluation.

Secrets and cloud access

Do not place tokens, private keys, or cloud credentials in workflow files. Prefer short-lived, federated credentials where the cloud platform and repository configuration support them. Scope secrets to the environment or job that needs them, and avoid printing them in shell commands. Treat pull request workflows from forks as untrusted: they should not receive production credentials, and workflows that execute contributor-controlled code should be designed with that boundary in mind. For a broader review of secret storage options, see the guide to secrets management tools.

Reusable workflows

When several repositories repeat the same build, scan, or deployment logic, move the stable portion into a reusable workflow. Keep application-specific inputs explicit rather than relying on repository naming conventions.

name: Shared deployment

on:
  workflow_call:
    inputs:
      environment:
        required: true
        type: string
      artifact-name:
        required: true
        type: string
    secrets:
      deploy-token:
        required: true

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: ${{ inputs.environment }}
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: ${{ inputs.artifact-name }}
      - env:
          DEPLOY_TOKEN: ${{ secrets.deploy-token }}
        run: ./scripts/deploy.sh ${{ inputs.environment }}

Callers can then provide the environment and artifact name while the shared workflow owns the common deployment sequence. Version shared workflows deliberately and test changes against a representative repository before applying them everywhere.

Examples

Monorepo with selective jobs

A monorepo can use path filters or a change-detection step to avoid rebuilding unrelated services. Keep the dependency graph visible: if a shared library changes, include every service that consumes it. For critical repositories, a full validation workflow can still run on a schedule so that skipped paths do not hide drift.

Kubernetes deployment

A Kubernetes workflow typically builds and scans an image, pushes it to a registry, updates a manifest or chart value with the immutable image reference, and waits for rollout status. Separate manifest validation from cluster access when possible. Production credentials should be available only to the protected deployment job, not to ordinary pull request checks. Include a clear failure path and a documented rollback command or revision strategy; a pipeline should not leave responders guessing how to return to the last known-good version.

Manual promotion

Some teams deploy automatically to a lower environment and require an approval before production. Model that decision with a protected production environment rather than adding a hidden sleep, an informal chat command, or a credential shared among engineers. The workflow should show who can approve, what artifact is being promoted, and what verification has already completed.

Reusable release process

A useful release workflow records the commit SHA, artifact name, environment, and result of post-deployment checks. These values make incident investigation faster and help connect a deployment to logs, metrics, and traces. If deployment affects a service monitored through OpenTelemetry, align the release metadata with the telemetry conventions described in the OpenTelemetry Collector configuration guide.

When to update

Revisit the workflow whenever its inputs or risk profile changes, not only when a GitHub Actions feature changes. Review it after any of the following events:

• A runtime, package manager, operating system, container base image, or deployment tool changes.
• The repository introduces a new service, build artifact, environment, or supported version.
• A security review identifies excessive permissions, long-lived credentials, unsafe pull request behavior, or incomplete scanning.
• The team changes its registry, cloud account structure, Kubernetes deployment method, or approval process.
• A failed release reveals missing verification, unclear rollback steps, or a misleading success condition.
• Shared reusable workflows or action dependencies are upgraded.

Make the next update practical. First, draw the current job dependency graph and mark where credentials enter. Second, identify whether each environment receives the same artifact. Third, run a failure exercise: stop a deployment after packaging, during rollout, and after a failed health check. Record the recovery command and add any missing verification to the workflow. Finally, review action versions, permissions, secrets, caches, and retention settings on a regular schedule that fits the repository’s change rate.

A good GitHub Actions CI/CD pipeline is not the longest one. It is a legible, repeatable path from a reviewed change to a verifiable release, with security boundaries and recovery steps that remain understandable as the project grows.