Uniport Workflows

A collection of reusable workflows and composite actions to avoid duplicating the content of workflows in GitHub actions.

Important

Start with these two articles in the GitHub Actions documentation: Reusing workflows and Avoiding duplication

Actions

Tip

Composite actions available in this repository.

• Abort if there is uncommitted code
• Add Helm repositories
• Disable man-db triggers
• Ensures a branch exists and aborts otherwise
• Parses the package version
• Send Rocket.Chat message
• Setup Java
• Setup Maven Build Variables
• Setup Maven Project Version
• Setup Nexus NPM Repository Access
• Setup Node.JS and NPM dependencies
• Validate Version

Workflows

Tip

Reusable workflows available in this repository.

• Archetype Update
• Changelog Update
• Deploy DEV
• Docker Images Move
• Git Patch Branch Create
• Git Tag Create
• Jira Release
• NPM Lint
• Nexus Artifacts Move
• Nexus Tag Associate
• Nexus Tag Create
• Nexus Tag Search
• Setup Maven Build Variables
• Tag Nexus Artifacts
• Version Bump

SBOM, Attestation & Dependency-Track

The shared build pipeline generates a CycloneDX SBOM for every build of the default branch and of X.Y.x maintenance branches (configurable via the sbom_ref_pattern input, opt out with generate_sbom: false):

• SBOM: npm frontend sources (production dependencies) plus a syft scan of every Docker image the build pushed, merged into a single sbom.cyclonedx.json run artifact. The npm project comes from sbom_npm_path (default frontend/src/main/web), skipped when that path does not exist. Point it elsewhere for a frontend outside the default path, or set it to an empty string to opt out.

• Attestation: the SBOM and a SLSA provenance predicate are attached to each image (by digest) with cosign, signed with the Uniport key pair. The public key is cosign.pub. Verify with:

  cosign verify-attestation --key cosign.pub --type cyclonedx --insecure-ignore-tlog <image>@<digest>
  cosign verify-attestation --key cosign.pub --type slsaprovenance --insecure-ignore-tlog <image>@<digest>

• Dependency-Track: the SBOM is uploaded to dtrack.inventage.com under the project named after the repository, with the semver prefix of the build version as project version. Each build of a release line replaces the BOM, so the Dependency-Track project always reflects the current release candidate; releases need no additional upload. The upload runs on a self-hosted runner because Dependency-Track is only reachable from the internal network.

These steps live in the standalone reusable workflow shared-sbom.yml. The shared build pipeline calls it automatically. A pipeline that does not use the shared build pipeline can reuse the exact same steps by calling shared-sbom.yml with the build version once its Docker images are pushed to the staging registry (see uniport-gateway for an example):

jobs:
  build:
    # ... your build that pushes the Docker images ...
    outputs:
      VERSION: ${{ jobs.build.outputs.VERSION }}
  sbom:
    needs: [build]
    uses: uniport/workflows/.github/workflows/shared-sbom.yml@main
    with:
      version: ${{ needs.build.outputs.VERSION }}
    secrets:
      NEXUS3_PW: ${{ secrets.NEXUS3_PW }}
      COSIGN_PRIVATE_KEY: ${{ secrets.COSIGN_PRIVATE_KEY }}
      COSIGN_PASSWORD: ${{ secrets.COSIGN_PASSWORD }}
      DEPENDENCY_TRACK_API_KEY: ${{ secrets.DEPENDENCY_TRACK_API_KEY }}

The Dependency-Track upload needs a self-hosted runner on the internal network; the runner label is configurable via dtrack_runner (default: macduff). Public repositories point it at a runner group that allows public repositories (e.g. inventage-ephemeral-linux-amd64, ideally restricted to this workflow in the runner group settings), or set upload_to_dependency_track: false to skip the upload (SBOM generation and attestation still run). The upload job never runs in PR context, so fork code cannot reach the self-hosted runner through this workflow.

Required configuration (attestation and upload are skipped with a notice when the secrets are absent):

Kind	Name	Purpose
Secret	COSIGN_PRIVATE_KEY	Signing key for attestations
Secret	COSIGN_PASSWORD	Password for the signing key
Secret	DEPENDENCY_TRACK_API_KEY	Dependency-Track API key (BOM_UPLOAD, project creation)
Variable	DEPENDENCY_TRACK_PARENT_UUID	Object Identifier of the Uniport parent project
Variable	DEPENDENCY_TRACK_URL	Optional, defaults to https://dtrack.inventage.com

Workflows vs. Actions

Reusable workflows	Composite actions
A YAML file, very similar to any standard workflow file	An action containing a bundle of workflow steps
Each reusable workflow is a single file in the .github/workflows directory of a repository	Each composite action is a separate repository, or a directory, containing an action.yml file and, optionally, other files
Called by referencing a specific YAML file	Called by referencing a repository or directory in which the action is defined
Called directly within a job, not from a step	Run as a step within a job
Can contain multiple jobs	Does not contain jobs
Each step is logged in real-time	Logged as one step even if it contains multiple steps
Can connect a maximum of four levels of workflows	Can be nested to have up to 10 composite actions in one workflow
Can use secrets	Cannot use secrets

Development

Local Testing

Some workflows can be run locally using act.

Examples:

act -W '.github/workflows/test-validate-version.yml' --input version=9.5.0-202504281107-91-fc989f5 --container-architecture linux/amd64

act -j build -W '.github/workflows/test-maven.yml' --secret NEXUS3_PW=test --var NEXUS3_USER=test --container-architecture linux/amd64