GitHub Actions CI/CD

GitHub Actions — Reusable Workflow CI/CD Guideline

House standard for CI/CD on GitHub Actions, organized as a central library of reusable workflows (workflow_call) composed by thin per-repo callers. One platform repo owns the workflows; product repos invoke them. This keeps pipeline logic DRY, versioned, and auditable across every stack.

Examples use placeholders — ${ORG} (GitHub org), <stack> (java/krakend/ react/…), generic secret names. Replace with your real values; never commit account IDs, ARNs, or tokens.

1. Principles

• Reusable-first. Pipeline logic lives in workflow_call workflows in a central ${ORG}/ci-templates repo. Product repos hold a ~20-line caller only.
• Compose, don’t copy. A *-main-pipeline.yml orchestrates atomic reusable workflows via uses: + needs:. No step is duplicated across stacks.
• Stack taxonomy. Files named <stack>-<concern>.yml; cross-stack ones shared-<concern>.yml. Predictable, greppable.
• Everything gated, everything observable. Quality/security checks gate artifact+deploy; failures open issues and notify chat.
• Least privilege. Explicit permissions: per workflow; pin actions; prefer OIDC over long-lived cloud keys.
• Branch protection as code. Rulesets (JSON) version-control the merge rules.

2. Reusable workflow contract (workflow_call)

Every reusable workflow declares a typed interface: inputs (with type/required/default), secrets, and outputs wired from job/step outputs. Callers stay declarative.

1
# .github/workflows/java-build.yml  (reusable)
2
name: Java - Build
3
on:
4
  workflow_call:
5
    inputs:
6
      runner:            { type: string,  required: false, default: 'ubuntu-latest' }
7
      java_version:      { type: string,  required: false, default: '21' }
8
      java_distribution: { type: string,  required: false, default: 'temurin' }
9
      run_spotless:      { type: boolean, required: false, default: true }
10
      upload_artifact:   { type: boolean, required: false, default: true }
11
    secrets:
12
      GH_PACKAGES_USERNAME: { required: false }
13
      GH_PACKAGES_TOKEN:    { required: false }
14
    outputs:
15
      artifact_name:
16
        description: 'Name of the uploaded JAR artifact'
17
        value: ${{ jobs.build.outputs.artifact_name }}
18

19
jobs:
20
  build:
21
    runs-on: ${{ inputs.runner }}
22
    timeout-minutes: 15
23
    permissions:
24
      contents: read
25
    outputs:
26
      artifact_name: ${{ steps.jar-info.outputs.name }}
27
    steps:
28
      - uses: actions/checkout@v5
29
      - uses: actions/setup-java@v5
30
        with:
31
          distribution: ${{ inputs.java_distribution }}
32
          java-version: ${{ inputs.java_version }}
33
      - name: Build
34
        env:
35
          GH_PACKAGES_USERNAME: ${{ secrets.GH_PACKAGES_USERNAME }}
36
          GH_PACKAGES_TOKEN: ${{ secrets.GH_PACKAGES_TOKEN }}
37
        run: ./gradlew clean build -x test --no-daemon --build-cache --parallel

Rules

• Inputs optional with sane defaults; boolean flags toggle stages.
• Declare each secret consumed; never read undeclared secrets.
• Expose outputs from step IDs (steps.<id>.outputs.<k> → job output → workflow output) so orchestrators can chain them.
• Set timeout-minutes and a minimal permissions: on every job.

3. Pipeline orchestration

A top-level pipeline composes reusable workflows. Stages run in parallel unless ordered by needs:; feature flags (run_* inputs) turn stages on/off; gating if: guards artifact/deploy on upstream success.

1
# java-main-pipeline.yml  (orchestrator, itself workflow_call)
2
jobs:
3
  commit-lint:
4
    if: inputs.run_commit_lint
5
    uses: ./.github/workflows/shared-commit-lint.yml
6

7
  build:
8
    if: inputs.run_build
9
    uses: ./.github/workflows/java-build.yml
10
    with: { upload_artifact: ${{ inputs.run_artifact }} }
11
    secrets: inherit
12

13
  test:
14
    if: inputs.run_test
15
    needs: build
16
    uses: ./.github/workflows/java-test.yml
17
    secrets: inherit
18

19
  artifact-ecr:
20
    if: |
21
      inputs.run_artifact && always() &&
22
      needs.build.result == 'success' &&
23
      (needs.test.result == 'success' || needs.test.result == 'skipped')
24
    needs: [build, test]
25
    uses: ./.github/workflows/shared-artifact-docker-ecr.yml
26
    with:
27
      artifact_name: ${{ needs.build.outputs.artifact_name }}
28
      image_tag: ${{ inputs.image_tag }}
29
    secrets: inherit
30

31
  deploy:
32
    if: inputs.run_deploy
33
    needs: [artifact-ecr]
34
    uses: ./.github/workflows/shared-deploy-eks.yml
35
    with: { image_tag: ${{ needs.artifact-ecr.outputs.image_tag }} }
36
    secrets: inherit

Job graph

1
commit-lint  security  dependency-review        (parallel, no deps)
2
        └─► build ─► test · owasp · code-analysis (parallel on build)
3
                 └─► artifact-* (gated on all checks green/skipped)
4
                          └─► deploy ─► release ─► tag
5
                                   └─► notify / create-issue-on-failure

Caller in a product repo — thin, just triggers + flags:

1
on:
2
  push:
3
    branches: [main, develop]
4
    paths-ignore: ['README.md', '.gitignore']
5
  workflow_dispatch:
6
concurrency:
7
  group: ${{ github.repository }}-${{ github.ref }}
8
  cancel-in-progress: true
9
jobs:
10
  pipeline:
11
    uses: ${ORG}/ci-templates/.github/workflows/java-main-pipeline.yml@v1
12
    with:
13
      run_test: true
14
      run_artifact: true
15
      run_deploy: true
16
    secrets: inherit

Rules

• Pass data between jobs only via needs.<job>.outputs.<key>.
• Use always() && needs.X.result == 'success' gates so skipped optional stages don’t block, but failed required stages do.
• Set concurrency to cancel superseded runs per ref.
• A separate *-pr-pipeline.yml runs lint/build/test/security on pull_request (no artifact/deploy).

4. Naming & taxonomy

Concerns: build, test, commit-lint, semver, artifact-docker-*, artifact-dependency-*, deploy-*, delete-branch, create-issue-on-failure, slack-notify, validate-source-branch, tag-release, release.

Promote a workflow to shared-* the moment a second stack needs it.

5. SemVer & release (from conventional commits)

Version is derived from commit history; tags + releases are automated. Pairs with git-workflow.md (conventional commits) — feat → minor, fix → patch, BREAKING CHANGE/MAJOR → major.

1
# shared-semver.yml (reusable)
2
on:
3
  workflow_call:
4
    inputs:
5
      tag_prefix:    { type: string, default: 'v' }
6
      major_pattern: { type: string, default: '(MAJOR|BREAKING CHANGE)' }
7
      minor_pattern: { type: string, default: '(feat)' }
8
    outputs:
9
      version: { value: ${{ jobs.semver.outputs.version }} }
10
jobs:
11
  semver:
12
    runs-on: ubuntu-latest
13
    outputs: { version: ${{ steps.ver.outputs.version }} }
14
    steps:
15
      - uses: actions/checkout@v5
16
        with: { fetch-depth: 0 }   # full history for version calc
17
      - id: ver
18
        uses: PaulHatch/semantic-version@v5.4.0
19
        with: { tag_prefix: ${{ inputs.tag_prefix }} }

Release stage tags vX.Y.Z, generates a changelog from commits, and creates the GitHub Release — runs only after a successful deploy. Tags are immutable (§8).

6. Security gates

Run as parallel jobs that gate artifact/deploy; keep them permissions: contents: read unless they must write.

1
# security-trufflehog.yml — pin third-party actions to a full SHA
2
- uses: trufflesecurity/trufflehog@37b77001d0174ebec2fcca2bd83ff83a6d45a3ab  # v3.95.3
3
  with:
4
    extra_args: ${{ inputs.only_verified && '--only-verified' || '' }}

OWASP gate pattern (parse JSON report, fail by severity):

CRITICAL=$(jq '[.dependencies[]?.vulnerabilities[]? | select(.severity=="CRITICAL")] | length' "$REPORT")
[ "$CRITICAL" -gt 0 ] && { echo "::error::$CRITICAL CRITICAL vulns"; exit 1; }

7. Deploy

Reusable shared-deploy-* per target (EKS, EC2, S3). Take image_tag + environment; bind to a GitHub Environment for approvals/secrets.

1
deploy:
2
  environment: ${{ inputs.environment }}   # enables required reviewers + env secrets
3
  permissions:
4
    id-token: write      # OIDC — preferred over static keys
5
    contents: read
6
  steps:
7
    - uses: aws-actions/configure-aws-credentials@v4
8
      with:
9
        role-to-assume: ${{ secrets.AWS_DEPLOY_ROLE_ARN }}   # OIDC role, not access keys
10
        aws-region: ${{ secrets.AWS_REGION }}

Rules

• Prefer OIDC (id-token: write + role-to-assume) over AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY long-lived secrets.
• Gate prod deploys behind a GitHub Environment with required reviewers.
• Deploy the immutable artifact built earlier (needs.artifact.outputs.image_tag); never rebuild in the deploy job.
• One reusable workflow per target; pick the target via a caller input.

8. Branch protection as code (rulesets)

Store GitHub rulesets as JSON in .github/ruleset/ and apply via API/Terraform. Production branches (main, develop) and release tags are protected.

1
{
2
  "name": "Protect main (PR-only, 2 approvals, linear, squash)",
3
  "target": "branch",
4
  "enforcement": "active",
5
  "conditions": { "ref_name": { "include": ["refs/heads/main"] },
6
                  "repository_name": { "include": ["${ORG}-ms-*", "${ORG}-sdk-*"] } },
7
  "rules": [
8
    { "type": "deletion" },
9
    { "type": "non_fast_forward" },
10
    { "type": "required_linear_history" },
11
    { "type": "pull_request", "parameters": {
12
        "dismiss_stale_reviews_on_push": true,
13
        "require_last_push_approval": true,
14
        "required_approving_review_count": 2,
15
        "required_review_thread_resolution": true,
16
        "allowed_merge_methods": ["squash"] } },
17
    { "type": "required_status_checks", "parameters": {
18
        "strict_required_status_checks_policy": true,
19
        "required_status_checks": [ { "context": "validate / PR Quality Gates" } ] } }
20
  ],
21
  "bypass_actors": []
22
}

Tag ruleset (release immutability) — target: "tag", refs/tags/v[0-9]*.[0-9]*.[0-9]*, rules creation/deletion/non_fast_forward/update, bypass only the Actions bot + admin role. Use enforcement: "evaluate" to dry-run a ruleset before flipping to "active".

9. Cross-cutting reusable workflows

• commit-lint (shared-commit-lint.yml): npx commitlint over the PR commit range (--from base.sha --to head.sha) or HEAD~1..HEAD on push. Enforces conventional commits.
• create-issue-on-failure: opens a labelled GitHub issue with repo/branch/ actor/run-link when the pipeline fails.
• slack-notify: posts status to a channel on failure/deploy/release.
• delete-branch: deletes the merged source branch on push to a protected branch.
• validate-source-branch: enforces branch-naming (feature/*, fix/*, …) before allowing a PR to proceed.

10. CODEOWNERS, action pinning, permissions

• CODEOWNERS in .github/: at least a default owner (* @${TEAM}); scope per path for sensitive areas (/.github/workflows/ @${PLATFORM_TEAM}).
• Pin actions: first-party (actions/*, aws-actions/*) to a major tag (@v5); third-party to a full commit SHA with a version comment. Never use @main/@master.
• Permissions: set the minimum at workflow or job level. Default the repo to permissions: {} and grant per job (contents: read, add id-token: write only where OIDC is needed, packages: write only to publish).
• Secrets: pass with secrets: inherit to reusable workflows; declare each in the secrets: block; never echo a secret; mask derived values.

11. Consumer adoption (thin callers + GitFlow stage matrix)

The reusable workflows live once in the central ci-templates repo. Each product repo ships thin ~20-line callers that uses: them — no build logic, just with: inputs + secrets: inherit. Adopt a stack by copying its stage templates into .github/workflows/ and replacing <org>:

cp templates/java-validate.yml        .github/workflows/   # PR + branch gate
cp templates/java-develop-deploy.yml  .github/workflows/   # dev on merge
cp templates/java-release-deploy.yml  .github/workflows/   # staging on release/*
cp templates/java-main-deploy.yml     .github/workflows/   # prod on merge to main
# then: replace <org> with your GitHub org in each `uses:` line

GitFlow stage → caller matrix (one caller per lifecycle stage):

deploy_target input — pick per caller; the orchestrator routes to the matching shared-deploy-* workflow (§7):

Rules

• Callers stay declarative — only uses: + with: + secrets: inherit. Any real step belongs in the reusable library, not the caller.
• Pin uses: to a release tag (@v1) or SHA on prod-facing callers — not a moving branch (@main). §10.
• The validate job id must match the ruleset’s required-status-check context (e.g. validate / PR Quality Gates) — §8, or the gate silently passes.
• Ratchet quality gates per repo: set coverage_*_threshold / owasp_fail_on_cvss to the current baseline, raise over time — never a global hardcode.
• Document the required secrets per deploy_target (AWS/ECR always; EC2 SSH set for ec2/ec2-vpn; extra WG_* for ec2-vpn; SLACK_WEBHOOK_URL for notifications) in the caller header.

12. Anti-patterns

13. Pre-merge checklist

• New pipeline logic added as a reusable workflow_call, not inline per repo.
• Inputs typed with defaults; secrets declared; outputs wired from step IDs.
• Orchestrator gates artifact/deploy on upstream success/skipped.
• permissions: minimal per job; OIDC for cloud, no static keys.
• Actions pinned (tag for first-party, SHA for third-party); no @main.
• timeout-minutes + concurrency set.
• Security gates present (dependency review, secret scan, vuln scan) and gating.
• commit-lint runs; conventional commits enforced (see git-workflow.md).
• Prod deploy behind a GitHub Environment with required reviewers.
• Branch + tag rulesets updated if protection rules changed.
• No org-specific tokens (account IDs, ARNs, secret values) committed.

CI/CD on GitHub Actions via a central reusable-workflow library. Pairs with git-workflow.md (conventional commits + branching that drive semver), gradle.md (build tasks invoked by java-build), and security.md (what the security gates enforce).