GitHub Actions Workflows

This repository contains reusable GitHub Actions workflows for building, testing, and deploying applications. These workflows are designed to be called from other repositories using the workflow_call trigger.

Workflows Overview

build-docker.yml

Purpose: Builds and pushes a Docker image to Google Artifact Registry.

Type: Reusable workflow (called via workflow_call)

Inputs:

• app-name (required, string): Name of the application being built
• docker-context (required, string): Path to the Docker build context
• version (required, string): Version tag for the Docker image
• build-args (optional, string): Additional Docker build arguments

Secrets Required:

• GCLOUD_KEY_FILE: Google Cloud credentials JSON

Outputs:

• version: Version of the built Docker image
• tag: Full tag of the Docker image in Google Artifact Registry (format: us-west2-docker.pkg.dev/dezzles-apps/dezzles-apps-docker/{app-name}:{version})

Key Steps:

1. Checkout repository
2. Authenticate with Google Cloud
3. Configure Docker for Google Artifact Registry
4. Build and push Docker image using docker/build-push-action@v4
5. Send event notifications on success/failure

---

build-java-docker.yml

Purpose: Builds a Java application using Gradle, then packages and pushes it as a Docker image.

Type: Reusable workflow (called via workflow_call)

Inputs:

• app-name (required, string): Name of the Java application
• docker-context (required, string): Path to the Docker build context
• version (required, string): Version tag for the Docker image
• build-args (optional, string): Additional Docker build arguments

Secrets Required:

• GCLOUD_KEY_FILE: Google Cloud credentials JSON

Outputs:

• version: Version of the built Docker image
• tag: Full tag of the Docker image in Google Artifact Registry

Key Steps:

1. Checkout repository
2. Setup Java 21 with Gradle caching
3. Build Java application via ./gradlew build in the specified context
4. Authenticate with Google Cloud
5. Configure Docker for Google Artifact Registry
6. Build and push Docker image
7. Send event notifications on success/failure

---

cloud-run-spec-deploy.yml

Purpose: Deploys to Google Cloud Run using declarative spec metadata files. The specs being deployed will typically be using metadata spec files based on a project.yml and generated by the create-specs.yml workflow.

Type: Reusable workflow (called via workflow_call)

Inputs:

• app-name (required, string): Name of the application
• environment (required, string): Target environment (e.g., dev, staging, prod)

Secrets Required:

• GCLOUD_KEY_FILE: Google Cloud credentials JSON

Key Steps:

1. Checkout repository
2. Download cloud-run-specs artifact (generated by create-specs.yml)
3. Authenticate with Google Cloud
4. Deploy to Cloud Run using metadata file: {app-name}-{environment}.yml
   • Region: us-west1
5. Send event notifications on success/failure

---

create-config.yml

Purpose: Extracts and outputs application configuration including name, version, and build type information.

Type: Reusable workflow (called via workflow_call)

Outputs:

• app-name: Name of the application
• version: Version being built
• spec-file: Path to the generated spec file
• is-release: Boolean flag indicating if this is a release build

Key Steps:

1. Checkout repository
2. Run dezzles-apps/actions-config@main to extract configuration
3. Output configuration variables for use in downstream workflows

Note: This is a utility workflow typically called early in build pipelines to determine build parameters.

---

create-specs.yml

Purpose: Generates Google Cloud Run deployment specification files from a project configuration file.

Type: Reusable workflow (called via workflow_call)

Inputs:

• version (required, string): Version to include in specs
• spec (optional, string): Path to the spec template file (default: ./project.yml)

Key Steps:

1. Checkout repository
2. Run dezzles-apps/spec-creater@main to generate specs
   • Uses the provided spec template
   • Substitutes the version
3. Upload generated specs to artifacts with name cloud-run-specs

Output Artifacts:

• cloud-run-specs: Contains generated .yml spec files for Cloud Run deployment

Note: Specs are uploaded as artifacts for use by cloud-run-spec-deploy.yml.

---

functional-tests.yml

Purpose: Runs functional tests using Gradle and Karate testing framework, with test results publishing.

Type: Reusable workflow (called via workflow_call)

Inputs:

• env (required, string): Environment to test against (used as Karate environment profile)

Secrets Required:

• GCLOUD_KEY_FILE: Google Cloud credentials JSON (for event notifications)

Key Steps:

1. Checkout repository
2. Setup Java 21 with Gradle caching
3. Run functional tests using Gradle:

   ./gradlew functional-tests:test -Dkarate.env={env}
   

4. Publish test results to GitHub using test-summary/action@v2
   • Reads JUnit XML from functional-tests/build/test-results/**/*.xml
5. Send event notifications on success/failure

Note: Tests run against the specified environment using Karate's environment variable system.

---

publish-to-portfolio.yml

Purpose: Publishes built artifacts and version information to Portfolio

Type: Reusable workflow (called via workflow_call)

Inputs:

• version (required, string): Version to publish

Secrets Required:

• GCLOUD_KEY_FILE: Google Cloud credentials JSON

Key Steps:

1. Checkout repository
2. Send event notification that publishing is starting
3. Run dezzles-apps/action-event/actions/publish@main to publish
   • Passes the version to publish
4. Send event notifications on success/failure

Note: This workflow is typically called after successful deployment to document the released version.

---

9. sonar-scan.yml

Purpose: Performs code quality analysis using SonarQube with Gradle and JaCoCo code coverage.

Type: Reusable workflow (called via workflow_call)

Inputs:

• app-name (required, string): Name of the application/module to analyze

Secrets Required:

• SONAR_TOKEN: SonarQube authentication token

Key Steps:

1. Checkout repository with full history (fetch-depth: 0 for better analysis)
2. Setup Java 21
3. Cache SonarQube and Gradle packages for faster execution
4. Run SonarQube analysis:

   ./gradlew {app-name}:build jacocoTestReport sonar
   

   • Compiles the application module
   • Generates JaCoCo code coverage report
   • Sends results to SonarQube

Note: Requires proper SonarQube configuration in build.gradle or gradle.properties.

---

Common Workflow Patterns

Build and Deploy Pipeline

Typical workflow composition for building and deploying an application:

1. create-config.yml → Extract app name, version, and configuration
2. build-docker.yml or build-java-docker.yml → Build and push Docker image
3. create-specs.yml → Generate Cloud Run deployment specs
4. cloud-run-deploy.yml or cloud-run-spec-deploy.yml → Deploy to target environment
5. functional-tests.yml → Validate deployment with tests
6. publish-to-portfolio.yml → Publish release information

Quality Assurance Pipeline

• sonar-scan.yml → Run code quality analysis

Example: Complete Build and Deploy Workflow

Below is a real-world example of how these reusable workflows are composed together for a multi-service application (shiny-hunt):

name: Build And Deploy
on:
  push:

jobs:
  notify-start:
    runs-on: ubuntu-latest
    steps:
      - uses: dezzles-apps/action-event/actions/event@main
        id: event
        with:
          credentialsJson: ${{ secrets.GCLOUD_KEY_FILE }}
          message: "Starting build process for commit: ${{ github.event.head_commit.url }}"

  configuration:
    uses: dezzles-apps/actions/.github/workflows/create-config.yml@main
    needs: [ notify-start ]

  build-ui:
    uses: dezzles-apps/actions/.github/workflows/build-docker.yml@main
    needs: [ configuration ]
    with:
      app-name: shiny-hunt-ui
      docker-context: ./shiny-stats
      version: '${{ needs.configuration.outputs.version }}'
    secrets: inherit

  build-api:
    uses: dezzles-apps/actions/.github/workflows/build-java-docker.yml@main
    needs: [ configuration ]
    with:
      app-name: shiny-stats-java-server
      docker-context: ./shinyhunt
      version: '${{ needs.configuration.outputs.version }}'
    secrets: inherit

  generate-specs:
    uses: dezzles-apps/actions/.github/workflows/create-specs.yml@main
    needs: [ configuration ]
    with:
      version: '${{ needs.configuration.outputs.version }}'

  deploy-non:
    uses: dezzles-apps/actions/.github/workflows/cloud-run-spec-deploy.yml@main
    needs: [ generate-specs, build-ui, build-api ]
    with:
      environment: non
      app-name: shiny-hunt
    secrets: inherit

  functional-tests:
    uses: dezzles-apps/actions/.github/workflows/functional-tests.yml@main
    needs: [ deploy-non ]
    with:
      env: non
    secrets: inherit

  deploy-prod:
    uses: dezzles-apps/actions/.github/workflows/cloud-run-spec-deploy.yml@main
    needs: [ functional-tests ]
    with:
      environment: prod
      app-name: shiny-hunt
    secrets: inherit

  publish:
    uses: dezzles-apps/actions/.github/workflows/publish-to-portfolio.yml@main
    needs: [ deploy-prod, configuration ]
    with:
      version: '${{ needs.configuration.outputs.version }}'
    secrets: inherit

Workflow Execution Flow

This example demonstrates:

1. notify-start: Send initial event notification
2. configuration: Extract version and app metadata (runs after notify-start)
3. build-ui and build-api: Build UI and API services in parallel using the extracted version
4. generate-specs: Generate Cloud Run deployment specs with the version
5. deploy-non: Deploy both services to the non-prod environment (waits for both builds and specs)
6. functional-tests: Run end-to-end tests against non-prod environment
7. deploy-prod: Deploy to production only after tests pass
8. publish: Publish the release to portfolio

This pipeline ensures:

• Parallel building: UI and API build simultaneously for faster execution
• Quality gates: Functional tests must pass before production deployment
• Version consistency: All components use the same version extracted from configuration
• Audit trail: Event notifications track progress at each stage
• Secrets management: Uses secrets: inherit to pass credentials through the workflow chain

Authentication

Most workflows require Google Cloud authentication via the GCLOUD_KEY_FILE secret. This should be set at the repository or organization level and contain a Google Cloud service account JSON key with appropriate permissions for:

• Docker registry access (Google Artifact Registry)
• Cloud Run deployments
• Event/notification system access

Event Tracking

Workflows use a custom dezzles-apps/action-event action to send event notifications for build start, success, and failure. This integrates with the build engine and sends notifications to Discord.

Notes

• All workflows are designed to be idempotent and safe to retry
• Workflows use event notifications for audit trails and status updates
• Java-based builds use Gradle with caching for faster execution
• Cloud Run deployments target the us-west1 region
• Docker images are pushed to Google Artifact Registry at us-west2-docker.pkg.dev/dezzles-apps/dezzles-apps-docker/