GitHub Workflows & Optum EPL Reusable Workflows Guide

This guide provides comprehensive documentation for utilizing Optum's Enterprise Platform Library (EPL) reusable workflows for seamless CI/CD builds with GitHub Actions.

Overview
Core Requirements
Available Workflows by Technology
Workflow Parameters
Getting Started
Examples Repository
Additional Resources

Overview

The EPL reusable workflows provide standardized CI/CD patterns that:

Build applications using language-specific build tools
Scan for security vulnerabilities and code quality issues
Publish container images to SaaS Artifactory
Integrate with OIDC authentication for secure deployments
Support multiple programming languages and frameworks

All workflows follow the pattern: uhg-pipelines/ci-workflows/.github/workflows/<language>-ci.yml@v2

Core Requirements

Required Runner

Always use uhg-runner for GitHub Actions due to security and IP whitelisting requirements.

Required Permissions

permissions:
  actions: read
  contents: write
  pull-requests: write
  security-events: write
  checks: write
  id-token: write  # Critical for OIDC authentication

Required Configuration

SaaS Artifactory: See artifactory.instructions.md for authentication setup
AWS OIDC: See aws-oidc.instructions.md for cloud resource authentication
Golden Images: Must use Optum-approved container base images

Available Workflows by Technology

Node.js Applications

NPM Workflow

Workflow: uhg-pipelines/ci-workflows/.github/workflows/node-npm-ci.yml@v2

Use When: Building Node.js applications using npm as the package manager

Example:

name: Node NPM CI
on:
  workflow_dispatch:
  pull_request:
    branches: [main]
    types: [opened, reopened, synchronize, ready_for_review]
  push:
    branches: ["release/**", main]

concurrency:
  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
  cancel-in-progress: true

jobs:
  node-ci-reusable:
    uses: uhg-pipelines/ci-workflows/.github/workflows/node-npm-ci.yml@v2
    with:
      jfrog-project-key: your-project-key
      docker-tags: centraluhg.jfrog.io/your-project-docker-np-loc/your-app:1.0.${{ github.run_number }}
      docker-context: '.'
      docker-dockerfile: 'Dockerfile'
      node-version: "20"

Demo: Node NPM Demo

Yarn Workflow

Workflow: uhg-pipelines/ci-workflows/.github/workflows/node-yarn-ci.yml@v2

Use When: Building Node.js applications using Yarn as the package manager

Demo: Node Yarn Demo

PNPM Workflow

Workflow: uhg-pipelines/ci-workflows/.github/workflows/node-pnpm-ci.yml@v2

Use When: Building Node.js applications using PNPM as the package manager

Demo: Node PNPM Demo

Python Applications

Pip Workflow

Workflow: uhg-pipelines/ci-workflows/.github/workflows/python-pip-ci.yml@v2

Use When: Building Python applications using pip for dependency management

Example:

name: Python Pip CI
on:
  workflow_dispatch:
  pull_request:
    branches: [main]
  push:
    branches: ['release/**', main]

jobs:
  build-and-quality-scans:
    uses: uhg-pipelines/ci-workflows/.github/workflows/python-pip-ci.yml@v2
    with:
      jfrog-project-key: your-project-key
      docker-tags: centraluhg.jfrog.io/your-project-docker-np-loc/your-app:1.0.${{ github.run_number }}
      source-dir: 'src'
      test-dir: 'tests'
      artifact-upload: true

Demo: Python Pip Demo

Poetry Workflow

Workflow: uhg-pipelines/ci-workflows/.github/workflows/python-poetry-ci.yml@v2

Use When: Building Python applications using Poetry for dependency management

Demo: Python Poetry Demo

Java Applications

Maven Workflow

Workflow: uhg-pipelines/ci-workflows/.github/workflows/java-maven-ci.yml@v2

Use When: Building Java applications using Maven

Example:

name: Java Maven CI
jobs:
  build-and-quality-scans:
    uses: uhg-pipelines/ci-workflows/.github/workflows/java-maven-ci.yml@v2
    with:
      jfrog-project-key: your-project-key
      docker-tags: centraluhg.jfrog.io/your-project-docker-np-loc/your-app:1.0.${{ github.run_number }}
      java-version: "17"

Demo: Java Maven Demo

Gradle Workflow

Workflow: uhg-pipelines/ci-workflows/.github/workflows/java-gradle-ci.yml@v2

Use When: Building Java applications using Gradle

Demo: Java Gradle Demo

.NET Applications

Workflow: uhg-pipelines/ci-workflows/.github/workflows/dotnet-ci.yml@v2

Use When: Building .NET applications (ASP.NET, .NET Core, etc.)

Example:

name: Dotnet CI
jobs:
  build-and-quality-scans:
    uses: uhg-pipelines/ci-workflows/.github/workflows/dotnet-ci.yml@v2
    with:
      jfrog-project-key: your-project-key
      docker-tags: centraluhg.jfrog.io/your-project-docker-np-loc/your-app:1.0.${{ github.run_number }}
      dotnet-version: 8.0.x
      dotnet-publish: true
      dotnet-publish-project-path: src/YourApp/YourApp.csproj

Demo: .NET Demo

Go Applications

Workflow: uhg-pipelines/ci-workflows/.github/workflows/go-ci.yml@v2

Use When: Building Go applications

Example:

name: Golang CI
jobs:
  build-and-quality-scans:
    uses: uhg-pipelines/ci-workflows/.github/workflows/go-ci.yml@v2
    with:
      jfrog-project-key: your-project-key
      docker-tags: centraluhg.jfrog.io/your-project-docker-np-loc/your-app:1.0.${{ github.run_number }}
      go-deploy: true
      go-private-orgs: github.com/uhg-internal

Demo: Go Demo

Scala SBT Applications

Workflow: uhg-pipelines/ci-workflows/.github/workflows/scala-sbt-ci.yml@v2

Use When: Building Scala applications using SBT

Example:

name: Scala SBT CI
jobs:
  get-version:
    runs-on: uhg-runner
    steps:
      - uses: actions/checkout@v4
      - id: get-version
        uses: uhg-pipelines/epl-version/generate-manifest-tag@v1
        with:
          version-type: date-sha
    outputs:
      version: ${{ steps.get-version.outputs.docker-tag }}

  build-and-quality-scans:
    needs: get-version
    uses: uhg-pipelines/ci-workflows/.github/workflows/scala-sbt-ci.yml@v2
    with:
      jfrog-project-key: your-project-key
      docker-tags: centraluhg.jfrog.io/your-project-docker-np-loc/your-app:${{ needs.get-version.outputs.version }}
      java-version: "11"
      sbt-build-command: clean test stage
      publish-version: ${{ needs.get-version.outputs.version }}

Demo: Scala SBT Demo

Docker-Only Builds

Workflow: uhg-pipelines/ci-workflows/.github/workflows/docker-ci.yml@v2

Use When: Building Docker images without language-specific build steps

Example:

name: Docker CI
jobs:
  docker-build-and-scans:
    uses: uhg-pipelines/ci-workflows/.github/workflows/docker-ci.yml@v2
    with:
      jfrog-project-key: your-project-key
      docker-tags: centraluhg.jfrog.io/your-project-docker-np-loc/your-app:1.0.${{ github.run_number }}
      docker-context: '.'
      docker-dockerfile: 'Dockerfile'

Demo: Docker Demo

Terraform Providers

Workflow: uhg-pipelines/ci-workflows/.github/workflows/terraform-provider-ci.yml@v2

Use When: Building and publishing Terraform providers

Example:

name: Terraform Provider CI
jobs:
  build-and-quality-scans:
    uses: uhg-pipelines/ci-workflows/.github/workflows/terraform-provider-ci.yml@v2
    with:
      jfrog-project-key: your-project-key
      working-directory: '.'
      tf-provider-deploy: "true"

Demo: Terraform Provider Demo

Workflow Parameters

Common Required Parameters

All workflows require these parameters:

Parameter	Description	Example
`jfrog-project-key`	JFrog Artifactory project identifier	`your-team-project`
`docker-tags`	Container image tags for publishing	`centraluhg.jfrog.io/your-project-docker-np-loc/app:1.0.0`

Common Optional Parameters

Parameter	Description	Default
`docker-context`	Build context directory	`.`
`docker-dockerfile`	Dockerfile path	`Dockerfile`
`working-directory`	Working directory for commands	`.`
`runs-on`	Runner type	`uhg-runner`

Runner Label	Description	Runner Group	Current Image	CPU	Memory
`uhg-runner`	Generic ARC Runners, should be good for most uses.	UHG Enterprise ARC	Defined in epl-arc-config	4	8GB
`uhg-runner-m`	Generic ARC Runners, medium sizing. Good for larger, more complex codebases up to 100k lines.	UHG Enterprise ARC	Defined in epl-arc-config	6	16GB
`uhg-runner-l`	Generic ARC Runners, large sizing. Limited access only for the largest codebases in the 1m+ line range and most complex automations	UHG Enterprise ARC	Defined in epl-arc-config	8	24GB
`runnerstage`	Pre-production runner image to validate image is viable before promoting to uhg-runner. Bleeding edge Optum base image. Feel free to use if you'd like to help us test.	ghec-runnerstage	Defined in epl-arc-config	2	2GB

Language-Specific Parameters

Node.js

node-version: Node.js version (e.g., "20")
upload-artifacts-name: Artifact bundle name
upload-artifacts-path: Files to upload as artifacts

Python

python-version: Python version (e.g., "3.11")
source-dir: Source code directory
test-dir: Test directory
artifact-upload: Enable artifact upload (boolean)

Java

java-version: Java version (e.g., "17")
java-distribution: Java distribution (e.g., "temurin")

.NET

dotnet-version: .NET version (e.g., "8.0.x")
dotnet-publish: Enable publishing (boolean)
dotnet-publish-project-path: Project file path
dotnet-pack-args: Additional pack arguments

Go

go-deploy: Enable deployment (boolean)
go-private-orgs: Private Go module organizations

Scala

sbt-build-jvm-args: JVM arguments for SBT
sbt-build-command: SBT build command
sbt-publish-command: SBT publish command
publish-version: Version for publishing

Getting Started

Step 1: Choose Your Workflow

Select the appropriate reusable workflow based on your technology stack from the sections above.

Step 2: Set Up Required Infrastructure

Artifactory Access: Ensure you have access to SaaS Artifactory with your project key
Golden Images: Verify your Dockerfile uses Optum golden images
Repository Settings: Configure GitHub repository permissions

Step 3: Create Workflow File

Create .github/workflows/<name>-ci.yml in your repository:

name: CI Pipeline
on:
  workflow_dispatch:
  pull_request:
    branches: [main]
    types: [opened, reopened, synchronize, ready_for_review]
  push:
    branches: ["release/**", main]

concurrency:
  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
  cancel-in-progress: true

permissions:
  actions: read
  contents: write
  pull-requests: write
  security-events: write
  checks: write
  id-token: write

jobs:
  build-and-quality-scans:
    uses: uhg-pipelines/ci-workflows/.github/workflows/<language>-ci.yml@v2
    with:
      jfrog-project-key: your-project-key
      docker-tags: centraluhg.jfrog.io/your-project-docker-np-loc/your-app:1.0.${{ github.run_number }}
      # Add language-specific parameters

Step 4: Configure Dockerfile

Ensure your Dockerfile uses golden images:

ARG JF_EDGE_NODE=edgeinternal1uhg.optum.com
FROM $JF_EDGE_NODE/glb-docker-uhg-loc/uhg-goldenimages/node:20.19-latest

ARG CHAINGUARD_USER_AND_GROUP=65532
WORKDIR /usr/src/app
COPY . .

RUN chown -R $CHAINGUARD_USER_AND_GROUP:$CHAINGUARD_USER_AND_GROUP /usr/src/app

EXPOSE 8080
USER $CHAINGUARD_USER_AND_GROUP
ENTRYPOINT ["node", "src/index.js"]

Step 5: Test and Deploy

Commit your workflow file
Create a pull request to trigger the workflow
Monitor the workflow execution in GitHub Actions
Verify the container image is published to Artifactory

Examples Repository

Primary Resource: uhg-pipelines/ci-workflows-demos

This repository contains complete, working examples for all supported technologies:

Directory Structure

ci-workflows-demos/
├── .github/workflows/          # Demo workflow files
│   ├── docker-ci-demo.yml
│   ├── dotnet-ci-demo.yml
│   ├── go-ci-demo.yml
│   ├── java-gradle-ci-demo.yml
│   ├── java-maven-ci-demo.yml
│   ├── node-npm-ci-demo.yml
│   ├── node-pnpm-ci-demo.yml
│   ├── node-yarn-ci-demo.yml
│   ├── python-pip-ci-demo.yml
│   ├── python-poetry-ci-demo.yml
│   ├── scala-sbt-ci-demo.yml
│   └── terraform-provider-ci-demo.yml
└── products/                   # Demo application code
    ├── docker/
    ├── dotnet/
    ├── go/
    ├── java-gradle/
    ├── java-maven/
    ├── node-npm/
    ├── node-pnpm/
    ├── node-yarn/
    ├── python-pip/
    ├── python-poetry/
    ├── scala-sbt/
    └── terraform-provider/

Exploring Examples

Use GitHub CLI to explore examples:

# Clone the repository
gh repo clone uhg-pipelines/ci-workflows-demos

# View specific workflow
gh api repos/uhg-pipelines/ci-workflows-demos/contents/.github/workflows/node-npm-ci-demo.yml

# Browse demo applications
gh repo view uhg-pipelines/ci-workflows-demos --web

Recommended: AI-Powered Code Review Integration

Code-Review-Agent Overview

The Code-Review-Agent is an AI-based tool that automatically reviews pull requests using GPT-4.1/GPT-4o models. It provides intelligent code quality feedback and can be customized for Optum-specific standards.

Why Use It?

Complements EPL Workflows: Runs after build/scan steps as an additional quality gate
Enforces Standards: Custom instructions enforce Optum enterprise coding standards
Team-Specific: Define your own code review parameters in markdown files
Non-Blocking: Graceful fallback if configuration is missing
Metrics: Reports to OTDataHub and AI SDLC Dashboard

Quick Setup

Step 1: Create custom instructions file at .github/code-review-instructions.md

# Optum Code Review Standards

## Golden Image Compliance
Verify all Dockerfiles use Optum golden images from edgeinternal1uhg.optum.com. No external base images allowed.

## Harmony UI Usage
Ensure React components use @uhg-harmony/react library. Check for proper license key configuration.

## Security Standards
Verify no secrets in code, OIDC authentication for AWS/Artifactory, non-root container users.

## Supply Chain Compliance
Check package dependencies are 5+ days old per npm.instructions.md, proper overrides configured.

## Documentation Quality
Verify requirements.md, design.md, tasks.md updated per spec-driven workflow.

Step 2: Add code review job to your workflow

name: Complete CI/CD with Code Review

on:
  pull_request:
    types: ["ready_for_review", "opened", "synchronize"]
    branches: [main]

permissions:
  actions: write
  contents: write
  pull-requests: write
  security-events: write
  checks: write
  id-token: write

jobs:
  # Build and quality scans using EPL workflows
  build-and-scan:
    uses: uhg-pipelines/ci-workflows/.github/workflows/node-npm-ci.yml@v2
    with:
      jfrog-project-key: your-project-key
      docker-tags: centraluhg.jfrog.io/your-project-docker-np-loc/app:${{ github.run_number }}

  # AI-powered code review after successful build
  code-review:
    needs: build-and-scan
    if: ${{ github.event.pull_request.draft == false }}
    uses: optum-eeps/Code-Review-Agent/.github/workflows/pr-code-review.yml@v2
    with:
      enable-custom-instructions: true
      code-report: concise
      model: gpt-4.1
      ignore-path-patterns: |
        node_modules/
        dist/
        coverage/
    secrets:
      github-token: ${{ secrets.GITHUB_TOKEN }}

Custom Instructions Formats

Header-Based Format (Recommended)

# Code Review Instructions

## TypeScript Type Safety
Ensure proper TypeScript types throughout. Check for 'any' types that should be replaced with interfaces.

## API Security
Review all API endpoints for authentication, input validation, rate limiting, and CORS configuration.

## Performance
Look for unnecessary API calls, inefficient re-renders, and optimization opportunities.

Bullet List Format

- **Maintainability**: Ensure clear naming conventions and documentation
- **Security**: Verify input validation and no hardcoded credentials
- **Testing**: Check adequate test coverage for new functionality

Configuration Options

Parameter	Type	Default	Description
`enable-custom-instructions`	boolean	`false`	Enable custom instructions from markdown file
`custom-code-quality-prompt`	string	`""`	Inline custom prompt (alternative to file)
`code-report`	string	`concise`	Report verbosity: `concise` or `verbose`
`model`	string	`gpt-4.1`	LLM model: `gpt-4.1` or `gpt-4o`
`ignore-path-patterns`	string	See docs	Paths to ignore (gitignore format)

File Naming & Location

Valid Custom Instructions Files (must be in .github/ root):

.github/code-review-instructions.md ✅
.github/custom-instructions.md ✅
.github/review-instructions.md ✅
.github/instructions.md ✅

Invalid Locations:

.github/config/instructions.md ❌ (subfolder)
docs/instructions.md ❌ (wrong directory)
.github/custom-review.md ❌ (doesn't end with instructions.md)

Token Limits & Behavior

Token Range: 100 - 800,000 tokens (80,000 for GPT-4o)
Custom Instructions Limit: 1,500 tokens max
Missing File Behavior: Posts PR comment, continues with standard parameters
Validation: LLM validates parameters are code-quality related

Example Custom Instructions by Project Type

Frontend (React/TypeScript)

## TypeScript Type Safety
No 'any' types, proper interfaces for props/state, appropriate generic types.

## React Best Practices
Hooks used correctly, proper memoization, no inline function definitions in render.

## Accessibility
Semantic HTML, ARIA attributes, keyboard navigation, screen reader compatibility.

Backend (Java/Spring Boot)

## Spring Boot Best Practices
Proper use of annotations, constructor-based DI, appropriate @Transactional usage.

## API Design
RESTful conventions, proper HTTP status codes, validated DTOs, consistent versioning.

## Database Performance
Check for N+1 queries, proper JPA fetch strategies, appropriate indexes.

Resources

Full Documentation: Custom Instructions Guide
Repository: optum-eeps/Code-Review-Agent
Examples: Prompt Templates

Additional Resources

Documentation Links

Artifactory Setup: See artifactory.instructions.md in this repository
AWS OIDC Setup: See aws-oidc.instructions.md in this repository
Golden Images: See optum-golden-containers.instructions.md in this repository
Docker Best Practices: See docker.instructions.md in this repository

EPL Resources

CI Workflows Repository: uhg-pipelines/ci-workflows
EPL Actions: optum-eeps/epl-actions
HCP Console: https://console.hcp.uhg.com/products/artifactory-saas

Support

EPL Team: For questions about reusable workflows
Artifactory Office Hours: Regular support sessions
Dojo360: https://dojo360.optum.com/chc-github-migration/

Best Practices

Workflow Configuration

Use Version Pinning: Always specify @v2 or specific version tags
Concurrency Control: Include concurrency groups to cancel redundant builds
Path Filters: Use specific paths to trigger builds only when relevant files change
Semantic Versioning: Use meaningful tags for container images

Security & Compliance

OIDC Authentication: Always use OIDC for authentication (never hardcode credentials)
Golden Images: Only use Optum-approved container base images
Secret Management: Use GitHub Secrets or external secret managers
Minimal Permissions: Grant only necessary permissions to workflows

Performance Optimization

Selective Triggers: Use path-based triggering to avoid unnecessary builds
Caching: Leverage built-in caching in EPL workflows
Parallel Jobs: Structure workflows for maximum parallelization
Resource Limits: Define appropriate resource constraints in Dockerfiles

Note: This documentation is maintained by the Optum EPL team. For the latest updates and detailed setup instructions, always refer to the official ci-workflows repository and ci-workflows-demos repository.

github-workflows

GitHub Workflows & Optum EPL Reusable Workflows Guide

Table of Contents

Overview

Core Requirements

Required Runner

Required Permissions

Required Configuration

Available Workflows by Technology

Node.js Applications

NPM Workflow

Yarn Workflow

PNPM Workflow

Python Applications

Pip Workflow

Poetry Workflow

Java Applications

Maven Workflow

Gradle Workflow

.NET Applications

Go Applications

Scala SBT Applications

Docker-Only Builds

Terraform Providers

Workflow Parameters

Common Required Parameters

Common Optional Parameters

Language-Specific Parameters

Node.js

Python

Java

.NET

Go

Scala

Getting Started

Step 1: Choose Your Workflow

Step 2: Set Up Required Infrastructure

Step 3: Create Workflow File

Step 4: Configure Dockerfile

Step 5: Test and Deploy

Examples Repository

Directory Structure

Exploring Examples

Recommended: AI-Powered Code Review Integration

Code-Review-Agent Overview

Quick Setup

Custom Instructions Formats

Configuration Options

File Naming & Location

Token Limits & Behavior

Example Custom Instructions by Project Type

Resources

Additional Resources

Documentation Links

EPL Resources

Support

Best Practices

Workflow Configuration

Security & Compliance

Performance Optimization