GitHub Actions

GitHub Actions is DIT's standard platform for continuous integration and continuous delivery (CI/CD). All automated workflows—including builds, tests, security scans, and deployments—are defined as GitHub Actions workflows.

Reusable Workflows

DIT maintains centralized reusable workflows in the ditkrg/actions repository. These ensure consistency across all projects and reduce duplication.

Available Workflows

Workflow	Purpose
dotnet-ci.yaml	.NET application build, test, and deploy
frontend-ci.yaml	Node.js frontend application build, test, and deploy (upcoming)
rails-ci.yaml	Rails application build, test, and deploy (upcoming)
go-ci.yaml	Go application build, test, and deploy (upcoming)

Build Image Action

For simpler workflows, use the ditkrg/build-image-workflow action directly:

- id: build-image
  name: Build and Push Image
  uses: ditkrg/build-image-workflow@v1
  with:
    image: my-team/my-app
    username: ${{ secrets.HARBOR_USER }}
    password: ${{ secrets.HARBOR_TOKEN }}

Using Reusable Workflows

# .github/workflows/ci.yaml
---
name: CI

on:
  push:
    branches:
      - dev
      - main
    tags:
      - v[0-9]+.[0-9]+.[0-9]+

    paths-ignore:
      - "**.md"
      - ".vscode/**"
      - ".github/**"
      - "!.github/workflows/ci.yaml"

jobs:
  ci:
    uses: ditkrg/actions/.github/workflows/dotnet-ci.yaml@main
    secrets: inherit
    with:
      sonarqube-enabled: ${{ github.ref_name == 'dev' }} # or leave empty to auto-detect
      sonarqube-project-key: sonarqube-project-key-here
      docker-image: my-team/my-app
      gitops-repo: my-app-gitops
      gitops-component-name: my-app-api

Triggers

Branch Triggers

on:
  push:
    branches:
      - dev    # Development environment
      - main   # Staging environment

Release Triggers

Production deployments are triggered by semantic version tags:

on:
  push:
    tags:
      - v[0-9]+.[0-9]+.[0-9]+  # Matches v1.0.0, v2.1.3, etc.

Path Filters

Optimize CI by ignoring non-essential files:

paths-ignore:
  - "**.md"
  - ".vscode/**"
  - ".github/**"
  - "!.github/workflows/ci.yaml"  # But DO run on workflow changes

Example CI Workflow

1. Test

• Restores packages/dependencies
• Runs dependencies using docker-compose
• Runs unit and integration tests
• Generates test coverage reports

2. SonarQube Analysis

When enabled, runs code quality and security analysis:

with:
  sonarqube-enabled: ${{ github.ref_name == 'dev' }}
  sonarqube-project-key: ditkrg_my-team-my-api

SonarQube analysis typically runs only on dev to avoid duplicate scans.

3. Build Docker Image

• Builds container image using the project's Dockerfile
• Tags with branch name (or version) and commit SHA
• Pushes to Harbor registry (reg.dev.krd)
• Checks the pushed image for a vulnerability scanning report (see PR Vulnerability Reports)

4. Update GitOps Repository

• Creates/updates image.yaml in the GitOps repository
• Includes image tag, digest, and source traceability:

global:
  image:
    tag: dev-843632a
    digest: sha256:570965b16c53e7fe6c48d50d8601a8cd2327143dba14412692a5b8fc2c119bf9
annotations:
  GITHUB_REPO_URL: https://github.com/ditkrg/my-team-my-api
  GITHUB_COMMIT_HASH: 843632abfd85fba907355af9f95755d0d40ce4b3

Environment-Specific Behavior

Branch/Tag	Target Environment	GitOps PR Approval
dev	Development	Auto-merge
main	Staging	Required
v*.*.*	Production	Required

Custom Workflows

For projects requiring custom CI steps, you can extend the standard workflow or create custom ones.

Example: Additional Pre-Build Steps

name: CI

on:
  push:
    branches: [dev, main]
    tags:
      - v[0-9]+.[0-9]+.[0-9]+

jobs:
  pre-build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Generate API client
        run: ./scripts/generate-client.sh

  ci:
    needs: pre-build
    uses: ditkrg/actions/.github/workflows/dotnet-ci.yaml@main
    secrets: inherit
    with:
      docker-image: my-team/my-api
      gitops-repo: my-team-gitops
      gitops-component-name: my-api

Testing in CI

Test Dependencies

The reusable CI workflows automatically start test dependencies using Docker Compose. If your project requires external services (databases, message brokers, etc.) for testing, create a docker-compose.tests.yml file:

# docker-compose.tests.yml
services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: test
      POSTGRES_PASSWORD: test
      POSTGRES_DB: test_db
    ports:
      - "5432:5432"

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

The workflow will automatically:

1. Look for docker-compose.tests.yaml or docker-compose.tests.yml
2. If not found, fall back to docker-compose.yml or docker-compose.yaml
3. Start the services before running tests
4. Tear down the services after tests complete

Running Tests

The reusable workflow automatically runs tests. Make sure your project's test command works successfully when run locally (outside of CI) to avoid unexpected failures in the workflow:

# .NET
dotnet test

# Node.js
pnpm test

# Go
go test ./...

Workflow Versioning

Pin reusable workflows to specific versions:

# ✅ Good - Pinned to main or specific version
uses: ditkrg/actions/.github/workflows/dotnet-ci.yaml@main
uses: ditkrg/actions/.github/workflows/dotnet-ci.yaml@v1

# ❌ Avoid - No version specified
uses: ditkrg/actions/.github/workflows/dotnet-ci.yaml

Debugging Workflows

View Workflow Runs

Navigate to the Actions tab in your GitHub repository.

Re-run Failed Jobs

Click Re-run jobs on a failed workflow run.

Enable Debug Logging

Add repository variable ACTIONS_STEP_DEBUG = true for verbose logging.

Security Best Practices

1. Use secrets: inherit

Pass organization secrets to reusable workflows:

jobs:
  ci:
    uses: ditkrg/actions/.github/workflows/dotnet-ci.yaml@main
    secrets: inherit  # ✅ Inherits org secrets

2. Never Hardcode Secrets

# ❌ Never do this
env:
  TOKEN: my-secret-token

# ✅ Use secrets
env:
  TOKEN: ${{ secrets.MY_TOKEN }}

3. Limit Workflow Permissions

permissions:
  contents: read
  packages: write

Concurrency Control

Prevent conflicting GitOps updates:

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: false

Dependabot

DIT uses GitHub Dependabot for automated dependency updates and security vulnerability detection.

Configuration

Create a .github/dependabot.yml file in your repository:

version: 2
updates:
  # GitHub Actions
  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "weekly"

  # Application dependencies (example for .NET)
  - package-ecosystem: "nuget"
    directory: "/"
    schedule:
      interval: "weekly"
    open-pull-requests-limit: 10

Supported Package Ecosystems

Ecosystem	Use Case
github-actions	GitHub Actions workflows
nuget	.NET / C# projects
npm	Node.js / JavaScript
gomod	Go modules
pip	Python
docker	Dockerfile base images

Handling Dependabot PRs

Dependabot PRs are automatically excluded from CI deployments:

if: ${{ github.actor != 'dependabot[bot]' }}

This prevents Dependabot PRs from triggering image builds and GitOps updates. After reviewing and merging a Dependabot PR, the normal CI pipeline runs.

Security Alerts

Dependabot automatically creates security alerts for vulnerable dependencies. These alerts appear in the repository's Security tab and should be addressed promptly.

PR Vulnerability Reports

When a build workflow completes, it automatically comments on any open Pull Request from that branch with a Harbor Image Vulnerability Report. This provides immediate visibility into security issues in your container images.

Example PR Comment

The workflow posts a comment like this:

🛡️ Harbor Image Vulnerability Report

Results for reg.dev.krd/my-team/my-api

🔍 Scan Summary

🧪 Total: 4 | 🔧 Fixable: 0
⚠️ Medium: 1 | 🟡 Low: 3

Scanned using Trivy v0.58.2 by Aqua Security

🔗 View Full Report in Harbor →

The comment includes expandable details for each vulnerability found:

• CVE ID and severity level
• Affected package and version
• Description of the vulnerability
• CVSS Score and CWE IDs
• Links to detailed vulnerability information

Benefits

• Early Detection: Security issues are surfaced during code review
• Actionable Information: Developers can see which vulnerabilities are fixable
• Traceability: Direct links to Harbor for full scan details
• Automatic Updates: Comments are updated on subsequent builds

Severity Levels

Icon	Severity	Action Required
🔴	Critical	Block merge, fix immediately
🟠	High	Should be addressed before merge
⚠️	Medium	Review and plan remediation
🟡	Low	Awareness, fix when possible

Notifications

Workflow failures are reported to:

• GitHub PR status checks
• Slack (configured via organization webhooks)

---

By using DIT's standardized GitHub Actions workflows, teams benefit from consistent CI/CD pipelines, automatic security scanning, and seamless GitOps integration.