Liquibase Reusable Workflows

Introduction to GitHub Actions

With GitHub Actions, you can create custom workflows for the software development lifecycle directly in your Github repository. These workflows consist of different tasks, called actions, that can be executed automatically when certain events occur.

At Liquibase, we use GitHub Actions for a wide range of tasks involved in the build, test, and release of extensions.

About reusable workflows

To avoid code duplication of GitHub Actions workflow files across thousands of repositories, we utilize reusable workflows. This allows us to DRY (don't repeat yourself) configurations, so we don't have to copy and paste workflows from one repository to another.

Calling reusable workflows

In the calling workflow file, use the uses property to specify the location and version of a reusable workflow file to run as a job.

name: { Job name }
on:
  pull_request:
jobs:
  { workflow }:
    uses: liquibase/build-logic/.github/workflows/{workflow}.yml@main

Calling reusable workflows with parameters

os-extension-test.yml and pro-extension-test.yml are triggered by a workflow call event and runs tests for Liquibase extensions (os/pro) on different Java versions and operating systems. The java input specifies the Java versions to test, and the os input specifies the operating systems to test. Both inputs are required and have default values.

name: { Job name }
on:
  pull_request:
jobs:
  { workflow }:
    uses: liquibase/build-logic/.github/workflows/{workflow}.yml@main
    with:
      java: "[17, 18]"
      os: '["ubuntu-latest", "windows-latest"]'

If inputs are not provided, '[8, 11, 17, 18]' and '["ubuntu-latest", "windows-latest"]' will be used as default values

package-deb.yml is triggered by a workflow call event and runs some Maven goals needed to create and distribute deb packages. It has several inputs:

groupId: Value from the groupId field in the pom file. i.e. org.liquibase
artifactId: Value from the artifactId field in the pom file. i.e. liquibase
version: Value from the version field in the pom file. i.e 4.23.1

🧩 Composite Action Wrappers

To reduce Dependabot noise and centralize SHA management, this repo provides composite action wrappers for high-frequency third-party actions. Instead of every repo pinning SHAs individually, repos reference the wrapper — and SHAs are updated in one place.

📦 Available Wrappers

Wrapper	Wraps	Usage
`checkout`	`actions/checkout`	`uses: liquibase/build-logic/.github/actions/checkout@main`
`setup-java`	`actions/setup-java`	`uses: liquibase/build-logic/.github/actions/setup-java@main`
`configure-aws-credentials`	`aws-actions/configure-aws-credentials`	`uses: liquibase/build-logic/.github/actions/configure-aws-credentials@main`
`setup-aws-vault`	AWS credentials + Secrets Manager	`uses: liquibase/build-logic/.github/actions/setup-aws-vault@main`
`setup-google-credentials`	Google Cloud credentials	`uses: liquibase/build-logic/.github/actions/setup-google-credentials@main`

🚀 Usage Example

Before (every repo pins its own SHA):

- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
  with:
    fetch-depth: 0

After (SHA managed centrally in build-logic):

- uses: liquibase/build-logic/.github/actions/checkout@main
  with:
    fetch-depth: 0

🔄 How SHA Updates Work

Dependabot monitors each composite action directory in build-logic
When a new version is released, Dependabot opens one PR in build-logic
After merge, all calling repos automatically use the updated SHA on next run
No more N Dependabot PRs across N repos for the same action update! 🎉

⚠️ Important Notes

Composite actions can only contain steps, not jobs
Calling repos reference wrappers with @main — a bad merge to build-logic affects all repos simultaneously
Always test composite action changes thoroughly before merging
Each wrapper passes through the full set of upstream inputs — see the action.yml for all available parameters

Example Build/Test/Release Extension Workflow

graph LR
    A[Feature Branch] -. Open Pull Request .-> B[Build Artifact, Test Matrix] & C[SonarCloud Scan]
    B & C -. Close Pull Request .-> D[Attach Artifact to Draft Release]
    D -. Push to Main .-> E[Create Draft Release] & F[SonarCloud Scan]
    E & F -. Publish Release .-> G[Release to Maven Central]

Please review the below table of reusable workflows and their descriptions:

Workflow	Description
`build-artifact.yml`	Runs maven build and saves artifacts
`build-extension-jar.yml`	Builds and deploys extension JARs to GitHub Package Manager
`cleanup-individual-artifacts.yml`	Cleans up individual OS-specific artifacts across multiple operating systems
`create-release.yml`	Runs Release Drafter to auto create draft release notes
`dependabot-automerge.yml`	Automatically merges Dependabot PRs for minor and patch updates
`fossa_ai.yml`	Runs FOSSA Scan for AI Generated Code
`ephemeral-cloud-infra.yml`	Creates/Destroys test automation cloud infrastructure
`extension-attach-artifact-release.yml`	Attaches a tested artifact to the draft release. Receives a `zip` input to upload generated zip files
`extension-release-prepare.yml`	Prepares extension release artifacts
`extension-release-published.yml`	Publishes a release to Maven Central
`extension-release-rollback.yml`	Rolls back a failed extension release
`extension-update-version.yml`	Updates release and development `pom.xml` versions
`fossa.yml`	Runs FOSSA license compliance checks and uploads reports
`fossa_ai.yml`	Scans code for AI-generated content and runs FOSSA license compliance
`generate-upload-fossa-report.yml`	Generates and uploads license reports to FOSSA
`lth-docker.yml`	Runs Liquibase Test Harness on Docker-based databases
`extension-automated-release.yml`	Unified workflow for OSS and commercial extension releases with automatic publishing to Maven Central
`os-extension-test.yml`	Unit tests across build matrix on previously built artifact
`owasp-scanner.yml`	Runs vulnerability scans using OWASP dependency checker
`package.yml`	Creates and distributes Linux packages (deb, rpm) and updates platform-specific repositories
`package-deb.yml`	Creates and uploads deb packages
`pom-release-published.yml`	Publishes a release pom to Maven Central
`pro-extension-build-for-liquibase.yml`	Builds and tests Pro extensions specifically for Liquibase
`pro-extension-test.yml`	Same as OS job, but with additional Pro-only vars such as License Key
`publish-for-liquibase.yml`	Publishes extensions for Liquibase consumption
`release-notes-aggregate.yml`	Aggregates `## Release note` H2 blocks from Done Jira tickets in a Fix Version and renders the release notes (preview-only on dry-run, or appends to the GitHub Release body on publish)
`slack-notification.yml`	Sends notifications to Slack when tests fail
`sonar-scan.yml`	Sonar code coverage scan for PRs and pushes (auto-detects context)
`sonar-coverage-merge.yml`	Merges unit/integration test coverage (JaCoCo) and runs Sonar scan for liquibase/liquibase-pro
`reusable-vulnerability-scan.yml`	Deep vulnerability scanning for Docker images and tarballs (nested JARs + Python packages)
various shell scripts	helper scripts for getting the draft release, signing artifacts, and uploading assets

Vulnerability Scanning

The reusable-vulnerability-scan.yml workflow provides deep vulnerability scanning for Docker images and tarballs. It extracts nested JARs (Spring Boot BOOT-INF/lib) and Python packages (GraalVM) that standard scanners miss.

Usage

Docker Image Scanning:

jobs:
  vulnerability-scan:
    uses: liquibase/build-logic/.github/workflows/reusable-vulnerability-scan.yml@main
    with:
      mode: docker
      source: "liquibase/liquibase-secure:latest"
      image_name: "liquibase-secure"
      image_tag: "latest"
      fail_on_vulnerabilities: true
      upload_sarif: true

Tarball Scanning:

jobs:
  vulnerability-scan:
    uses: liquibase/build-logic/.github/workflows/reusable-vulnerability-scan.yml@main
    with:
      mode: tarball
      source: "distribution-artifact"  # artifact name from upload-artifact
      version: "5.0.0"
      scan_scope: "python-only"
      fail_on_vulnerabilities: true

Inputs

Input	Type	Required	Default	Description
`mode`	string	yes	-	`docker` or `tarball`
`source`	string	yes	-	Docker image ref OR artifact name
`image_name`	string	no	`''`	Image name for reporting (docker mode)
`image_tag`	string	no	`''`	Image tag for reporting (docker mode)
`version`	string	no	`''`	Version for reporting (tarball mode)
`scan_scope`	string	no	`full`	`full` or `python-only`
`fail_on_vulnerabilities`	boolean	no	`true`	Fail on HIGH/CRITICAL
`upload_sarif`	boolean	no	`false`	Upload to GitHub Security tab
`sarif_category`	string	no	`vulnerability-scan`	SARIF category
`generate_sbom`	boolean	no	`true`	Generate SBOM (docker only)
`build_logic_ref`	string	no	`master`	build-logic branch/tag

Outputs

Output	Description
`total_vulnerabilities`	Total HIGH/CRITICAL count
`surface_vulnerabilities`	Surface scan count (docker only)
`deep_vulnerabilities`	Deep scan count
`grype_vulnerabilities`	Grype scan count (docker only)
`scan_status`	`pass` or `fail`

Suppressing False Positives

Two suppression mechanisms exist, applied independently by the reusable vulnerability-scan workflow:

Mechanism	Where it lives	Who uses it	Why
VEX (`vex/assessments.yaml`)	`liquibase/liquibase-pro`	`liquibase-secure` scans (`vex_enabled: true`)	Cross-scanner (Trivy + Grype + OSV), per-package, structured justifications. Single source of truth for the secure product.
`.trivyignore`	Calling repo (default path `docker/.trivyignore`)	Community / OSS Docker scans (TECHOPS-432)	Community workflows cannot reach `liquibase-pro/vex/assessments.yaml` (TECHOPS-408 forbids `dispatch_new_cves`). `.trivyignore` is the documented carve-out for these scans only.

The reusable workflow fetches the caller's .trivyignore via gh api contents/; missing file is a silent no-op (behavior identical to no input set).

Caller usage:

uses: liquibase/build-logic/.github/workflows/reusable-vulnerability-scan.yml@main
with:
  trivyignore_path: docker/.trivyignore   # default — override or set to '' to disable

File format & conventions (enforced by review, not CI):

Plain Trivy-native syntax (one CVE per line, # comments, exp:YYYY-MM-DD for expiry — Trivy auto-skips expired entries).
EVERY entry MUST be preceded by a # reason: comment block explaining the suppression.
Prefer a review-date (≤ 6 months) over no expiry.
For liquibase-secure, use VEX. .trivyignore is community-only.

When to use which:

Multi-scanner suppression needed → VEX (Trivy + Grype + OSV).
Single-scanner Trivy false positive on a community/OSS image → .trivyignore.
Pro-secure callers MUST NOT define .trivyignore unless explicitly waived; VEX is the canonical path.

The standalone build-logic/.trivyignore file at this repo root is a legacy copy-pattern artifact and is NOT applied by any current workflow. Cleanup is tracked separately.

Scripts

Scripts in scripts/vulnerability-scanning/ can be used directly:

Script	Description
`extract-nested-deps.sh`	Extract nested JARs and Python packages
`analyze-scan-results.sh`	Combine Trivy/Grype results
`convert-scan-results.sh`	Convert JSON to SARIF
`create-enhanced-report.sh`	Generate detailed markdown report
`append-github-summary.sh`	Append to GitHub Actions summary
`save-grype-results.sh`	Normalize Grype output filenames

Direct script usage:

# Docker mode - extract nested deps
build-logic/scripts/vulnerability-scanning/extract-nested-deps.sh \
  --mode=docker \
  --source="my-image:tag" \
  --scope=full

# Tarball mode - extract Python only
build-logic/scripts/vulnerability-scanning/extract-nested-deps.sh \
  --mode=tarball \
  --source="./path/to/tarball.tar.gz" \
  --scope=python-only

Release Notes Aggregation

The release-notes-aggregate.yml workflow walks every Done Jira ticket in a Fix Version, extracts the ## Release note H2 block from each ticket's description, and renders a paste-ready markdown release notes block plus a seven-bucket completeness report. Logic lives in scripts/release-notes/ (Python CLI, stdlib only, 70 pytest tests). Per TECHOPS-498.

Today's callers: liquibase/liquibase (Community), liquibase/liquibase-pro (Secure). Future repos (NTT, Platform, MCP) adopt by pasting the ~85-line caller and swapping the product prefix.

Operating modes

Mode	Trigger	Output	Use case
Dry-run preview	`workflow_dispatch` with `dry_run=true` (default)	Step summary + downloadable `release-notes` artifact	Release manager previews before publishing. GitHub Release body untouched.
Publish	`release: [published]` auto-trigger, or manual dispatch with `dry_run=false` + `release_tag`	Step summary + artifact + appended to the GitHub Release body	Production. Existing Release Drafter content is preserved with a `---` separator.

Usage

Manual preview (recommended starting point):

jobs:
  aggregate:
    uses: liquibase/build-logic/.github/workflows/release-notes-aggregate.yml@main
    with:
      version: "Community 5.0.4"   # or Secure / Platform / MCP X.Y.Z
      dry_run: true
    secrets: inherit

Auto-fire on release publish (publishes to release body):

on:
  release:
    types: [published]

jobs:
  derive:
    runs-on: ubuntu-latest
    outputs:
      version: ${{ steps.compute.outputs.version }}
    steps:
      - id: compute
        env:
          EVENT_TAG: ${{ github.event.release.tag_name }}
        run: |
          stripped="${EVENT_TAG#v}"
          echo "version=Community ${stripped}" >> "$GITHUB_OUTPUT"

  aggregate:
    needs: derive
    uses: liquibase/build-logic/.github/workflows/release-notes-aggregate.yml@main
    with:
      version: ${{ needs.derive.outputs.version }}
      dry_run: false
      release_tag: ${{ github.event.release.tag_name }}
    secrets: inherit

Swap Community for Secure, Platform, or MCP Changelog when adopting in another product repo.

Inputs

Input	Type	Required	Default	Description
`version`	string	yes	-	Jira Fix Version name (e.g. `Community 5.0.4`, `Secure 5.2.0`, `Platform 1.0.0`, `MCP Changelog 1.0.0`)
`dry_run`	boolean	no	`true`	If `true`: preview only in step summary + artifact, GitHub Release body untouched. If `false`: also append notes to the release body (requires `release_tag`).
`release_tag`	string	no	`""`	GitHub Release tag to update when `dry_run=false` (e.g. `v5.0.4`). Required when publishing, ignored on dry runs.
`build_logic_ref`	string	no	`main`	Ref of `liquibase/build-logic` to check out for the script. Pin to a tag in production callers for stable behaviour.

Auth

Same OIDC pattern as every other jira-* workflow in this repo: GitHub OIDC token → assumes org-level role LIQUIBASE_VAULT_OIDC_ROLE_ARN → pulls ,/vault/liquibase from AWS Secrets Manager → sets JIRA_USER + JIRA_API_TOKEN. Callers just say secrets: inherit.

Convention dependency

The aggregator reads ## Release note H2 blocks from each ticket's description. Engineers fill that in per the convention from TECHOPS-479. Tickets without an H2 are flagged in the completeness report (not silently dropped). The skipReleaseNotes label from TECHOPS-478 is honoured as an opt-out.

Completeness invariant

Every run prints a seven-bucket report; the three mutually-exclusive count buckets satisfy with_note + skipped + flagged == total_done. The script asserts this in code and the report renderer fails loudly if it doesn't hold.

Security

Every user-controllable input (inputs.version, inputs.release_tag, event payload fields) is consumed via env vars in run: blocks. Never interpolated directly into shell. Follows the GitHub workflow-injection guide.

Requirements

pom.xml

The pom must meet all the requirements from sonatype: https://central.sonatype.org/publish/requirements/#a-complete-example-pom

Jacoco

Jacoco must be configured and exporting test results.

<plugin>
    <groupId>org.jacoco</groupId>
    <artifactId>jacoco-maven-plugin</artifactId>
    <version>0.8.8</version>
    <configuration>
        <fileSets>
            <fileSet>
                <directory>target</directory>
                <includes>
                    <include>**/jacoco.exec</include>
                </includes>
            </fileSet>
        </fileSets>
    </configuration>
</plugin>

Surefire

All unit tests must run and pass with surefire:test. If any test require additional setup, such as docker, they will need to run separately from the reusable build logic.

<plugin>
    <artifactId>maven-surefire-plugin</artifactId>
    <version>2.22.2</version>
    <configuration>
        <redirectTestOutputToFile>true</redirectTestOutputToFile>
        <reportFormat>plain</reportFormat>
    </configuration>
</plugin>

Artifacts

The following artifacts must be created mvn clean package. If the javadoc and sources should not be public, please copy the contents of the readme for those files. This is based on the recommendation from sonatype: https://central.sonatype.org/publish/requirements/#supply-javadoc-and-sources.

{artifactId}-{version}.jar
{artifactId}-{version}.pom
{artifactId}-{version}-javadoc.jar
{artifactId}-{version}-sources.jar

<plugin>
    <groupId>com.coderplus.maven.plugins</groupId>
    <artifactId>copy-rename-maven-plugin</artifactId>
    <version>1.0</version>
    <executions>
        <execution>
            <id>copy</id>
            <phase>package</phase>
            <goals>
                <goal>copy</goal>
            </goals>
            <configuration>
                <fileSets>
                    <fileSet>
                        <sourceFile>${project.basedir}/pom.xml</sourceFile>
                        <destinationFile>${project.basedir}/target/${project.artifactId}-${project.version}.pom</destinationFile>
                    </fileSet>
                    <fileSet>
                        <sourceFile>${project.basedir}/README.md</sourceFile>
                        <destinationFile>${project.basedir}/target/${project.artifactId}-${project.version}-javadoc.jar</destinationFile>
                    </fileSet>
                    <fileSet>
                        <sourceFile>${project.basedir}/README.md</sourceFile>
                        <destinationFile>${project.basedir}/target/${project.artifactId}-${project.version}-sources.jar</destinationFile>
                    </fileSet>
                </fileSets>
            </configuration>
        </execution>
    </executions>
</plugin>

Maven release

The Maven release plugin must be configured to allow extensions update pom.xml versions:

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-release-plugin</artifactId>
            <version>${maven-release-plugin.version}</version>
            <configuration>
                <scmCommentPrefix>[Version Bumped to ${project.version}]</scmCommentPrefix>
            </configuration>
        </plugin>
    </plugins>
</build>

Version Bumping after Release

When releasing extensions, a Pull Request is automatically created to update the version in the pom.xml files instead of directly committing to the main branch. This approach provides the following benefits:

Improved security by requiring reviews before version changes are merged
Better traceability of version bumps through the PR history
Opportunity for validation before finalizing the version change

The PR creation is handled by the extension-release-prepare.yml workflow:

- name: Create Pull Request for version bump
  uses: peter-evans/create-pull-request@v7.0.8
  with:
    token: ${{ secrets.GITHUB_TOKEN }}
    commit-message: "chore: update version after release"
    title: "Version bump after release"
    body: |
      This PR updates the POM version after a release.

      Automated changes by GitHub Actions.
    branch: version-bump-after-release
    delete-branch: true

These version bump PRs are automatically merged through a nightly scheduled workflow (auto_merge_release_prs.yml) in the liquibase-infrastructure repository. This workflow:

Runs on a daily schedule (midnight UTC) or can be triggered manually
Identifies all repositories with the extension topic
Finds open PRs with the exact title "Version bump after release"
Merges these PRs using the squash strategy

This automation ensures that version bumps are consistently applied across all extension repositories without requiring manual intervention, while still maintaining the security benefits of the PR-based approach.

Liquibase Test Harness

Workflow	Description
`lth-docker.yml`	Runs Liquibase Test Harness against a docker container

Docker Databases

Requirements

Docker Compose file must be located in src/test/resources/docker-compose.yml

Liquibase test (unit & integration tests) + Sonar

The sonar-coverage-merge.yml reusable workflow merges unit and integration test JaCoCo coverage reports and delivers the aggregated report to SonarCloud. It downloads pre-generated coverage artifacts (liquibase-jacoco-test-results for unit tests, liquibase-integration-jacoco-test-results-* for integration tests), merges them using the JaCoCo CLI, and runs the Sonar scan.

This workflow supports both PR and branch scans, and is used by liquibase and liquibase-pro.

Configuration

The project has to be configured with the following Maven plugins:

Maven Surefire Plugin: Runs unit tests
Maven Failsafe Plugin: Runs integration tests
Jacoco Plugin: Generates test reports and it also agreggates and merges all of them into a single report

For Maven multimodule projects it is recommended to follow this pattern from SonarSource where there is a specific module to leave the aggregated report:

Multi-module Apache Maven example

In the following example we demonstrate how liquibase-pro works:

Parent pom.xml

All modules need to specify where the final report will be generated setting the sonar.coverage.jacoco.xmlReportPaths property. In the parent pom there are 3 profiles to control which tests are executed and the required plugins are configured.

    <properties>
        <maven-failsafe-plugin.version>3.0.0-M7</maven-failsafe-plugin.version>
        <jacoco-maven-plugin.version>0.8.5</jacoco-maven-plugin.version>
        <maven-surefire-plugin.version>3.0.0-M7</maven-surefire-plugin.version>
        <code.coverage.project.folder>${basedir}/../</code.coverage.project.folder>
        <code.coverage.overall.data.folder>${basedir}/target/</code.coverage.overall.data.folder>
        <skip.integration.tests>true</skip.integration.tests>
        <skip.unit.tests>true</skip.unit.tests>
        <itCoverageAgent></itCoverageAgent>
        <sonar.coverage.jacoco.xmlReportPaths>liquibase-pro-coverage/target/site/jacoco-aggregate/jacoco.xml</sonar.coverage.jacoco.xmlReportPaths>
    </properties>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-surefire-plugin</artifactId>
                <version>${maven-surefire-plugin.version}</version>
                <configuration>
                    <skipTests>${skip.unit.tests}</skipTests>
                    <excludes>
                        <exclude>liquibase-pro-integration-tests/**/*IntegrationTest.java</exclude>
                    </excludes>
                    <forkCount>1</forkCount>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-failsafe-plugin</artifactId>
                <version>${maven-failsafe-plugin.version}</version>
                <executions>
                    <execution>
                        <id>integration-tests</id>
                        <goals>
                            <goal>integration-test</goal>
                        <goal>verify</goal>
                        </goals>
                        <configuration>
                            <skipTests>${skip.integration.tests}</skipTests>
                            <includes>
                                <include>**/*IntegrationTest.java</include>
                            </includes>
                            <reuseForks>true</reuseForks>
                            <argLine>${itCoverageAgent}</argLine>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
            <plugin>
                <groupId>org.jacoco</groupId>
                <artifactId>jacoco-maven-plugin</artifactId>
                <version>${jacoco-maven-plugin.version}</version>
                <executions>
                    <execution>
                        <id>prepare-unit-tests</id>
                        <goals>
                            <goal>prepare-agent</goal>
                        </goals>
                    </execution>
                    <!-- prepare agent before integration tests -->
                    <execution>
                        <id>prepare-agent</id>
                        <goals>
                            <goal>prepare-agent</goal>
                        </goals>
                        <phase>pre-integration-test</phase>
                        <configuration>
                            <propertyName>itCoverageAgent</propertyName>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
            <plugin>
                <groupId>org.sonarsource.scanner.maven</groupId>
                <artifactId>sonar-maven-plugin</artifactId>
                <version>3.9.1.2184</version>
                <executions>
                    <execution>
                        <id>sonar</id>
                        <goals>
                            <goal>sonar</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>

    <profile>
        <id>unit</id>
        <properties>
            <skip.integration.tests>true</skip.integration.tests>
            <skip.unit.tests>false</skip.unit.tests>
        </properties>
    </profile>
    <profile>
        <id>integration-test</id>
        <properties>
            <skip.integration.tests>false</skip.integration.tests>
            <skip.unit.tests>true</skip.unit.tests>
        </properties>
    </profile>
    <profile>
        <id>testAll</id>
        <properties>
            <skip.integration.tests>false</skip.integration.tests>
            <skip.unit.tests>false</skip.unit.tests>
        </properties>
    </profile>

modules with integration tests (pom.xml)

maven-surefire-plugin had to be added here because liquibase-pro integration tests are not following the *ITest.java or *IntegrationTest.java naming for integration tests.

    <properties>
        <sonar.coverage.jacoco.xmlReportPaths>${project.basedir}/../liquibase-pro-coverage/target/site/jacoco-aggregate/jacoco.xml</sonar.coverage.jacoco.xmlReportPaths>
    </properties>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-surefire-plugin</artifactId>
                <configuration>
                    <skipTests>${skip.integration.tests}</skipTests>
                    <forkCount>1</forkCount>
                </configuration>
            </plugin>
        </plugins>
    </build>

Modules without integration tests (pom.xml)

    <properties>
        <sonar.coverage.jacoco.xmlReportPaths>${project.basedir}/../liquibase-pro-coverage/target/site/jacoco-aggregate/jacoco.xml</sonar.coverage.jacoco.xmlReportPaths>
    </properties>

Coverage module (pom.xml)

Here the modules we want to generate and aggregate test reports must be specified as dependencies.

    <properties>
        <sonar.coverage.jacoco.xmlReportPaths>target/site/jacoco-aggregate/jacoco.xml</sonar.coverage.jacoco.xmlReportPaths>
        <code.coverage.project.folder>${basedir}/../</code.coverage.project.folder>
        <code.coverage.overall.data.folder>${basedir}/target/</code.coverage.overall.data.folder>
        <sonar.skip>true</sonar.skip>
        <maven.deploy.skip>true</maven.deploy.skip>
    </properties>

    <dependencies>
        <dependency>
            <groupId>${project.groupId}</groupId>
            <artifactId>liquibase-commercial</artifactId>
            <version>${project.version}</version>
        </dependency>
            <dependency>
            <groupId>${project.groupId}</groupId>
            <artifactId>liquibase-commercial-integration-tests</artifactId>
            <version>${project.version}</version>
        </dependency>
    </dependencies>

    <build>
      <plugins>
        <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-surefire-plugin</artifactId>
          <configuration>
            <argLine>${argLine} -Xms256m -Xmx2048m</argLine>
            <forkCount>1</forkCount>
            <runOrder>random</runOrder>
          </configuration>
        </plugin>

        <plugin>
          <groupId>org.jacoco</groupId>
          <artifactId>jacoco-maven-plugin</artifactId>
          <executions>
            <execution>
              <id>report-aggregate</id>
              <phase>verify</phase>
              <goals>
                <goal>report-aggregate</goal>
              </goals>
            </execution>

            <execution>
              <id>merge-results</id>
              <phase>verify</phase>
              <goals>
                <goal>merge</goal>
              </goals>
              <configuration>
                <fileSets>
                  <fileSet>
                    <directory>${code.coverage.project.folder}</directory>
                    <includes>
                      <include>**/target/jacoco.exec</include>
                    </includes>
                  </fileSet>
                </fileSets>
                <destFile>${code.coverage.overall.data.folder}/aggregate.exec</destFile>
              </configuration>
            </execution>
          </executions>
        </plugin>
      </plugins>
    </build>

Releasing a new version of build-logic

When you want to release new version of build-logic, it is important to update all the occurrences of previous version eg: main with the new version eg : main in all the files. As, the code for the new version internally refers to the old version.

🔑 GitHub Tokens Strategy

Secure authentication and authorization are critical aspects of our CI/CD workflow. We employ different token types for various scenarios to optimize security and minimize GitHub API rate limit issues.

🔒 Default GITHUB_TOKEN

GitHub automatically provides a GITHUB_TOKEN secret that's available during workflow runs. This is a short-lived token that expires when the job completes.

When to use:

For single-repository operations
When no cross-repository access is needed
For most common GitHub API operations within the same repository

Security benefits:

Automatically rotated for each job
Limited to the repository where the workflow runs
Permissions can be explicitly scoped using the permissions key

permissions:
  id-token: write
  contents: write
  pull-requests: write

Example:

- name: Create Pull Request for version bump
  uses: peter-evans/create-pull-request@v7.0.8
  with:
    token: ${{ secrets.GITHUB_TOKEN }}
    commit-message: "chore: update version after release"
    title: "Version bump after release"

🔐 GitHub App Tokens

For operations that require cross-repository access or elevated permissions without using personal credentials, we use GitHub App tokens.

When to use:

For cross-repository operations (cloning, checking out)
When you need specific permissions across multiple repositories
For operations that would exceed rate limits with GITHUB_TOKEN

Security benefits:

Fine-grained permissions control
No personal credentials involved
Short-lived by default (can be configured)
Auditable through GitHub App activity. (Search filter: action:oauth_application)

Example:

- name: Get GitHub App token
  id: get-token
  uses: actions/create-github-app-token@v2
  with:
    app-id: ${{ env.LIQUIBASE_GITHUB_APP_ID }}
    private-key: ${{ env.LIQUIBASE_GITHUB_APP_PRIVATE_KEY }}
    owner: ${{ github.repository_owner }}
    permission-contents: read
    permission-packages: write

- name: Checkout code
  uses: actions/checkout@v4
  with:
    repository: ${{ inputs.repository }}
    token: ${{ steps.get-token.outputs.token }}

🪪 Personal Access Tokens (PATs)

While we minimize their use, PATs are sometimes necessary for specific scenarios where GitHub Apps or GITHUB_TOKEN aren't sufficient.

When to use:

When GitHub App tokens cannot provide the necessary access
For GitHub Package Manager (GPM) cross-repository access
For legacy integrations that don't support other authentication methods

Security considerations:

Store as encrypted repository secrets
Use fine-grained PATs with minimum required scopes (GPM cross-repo deploys requires classic PAT)
Regularly rotate tokens
Consider using organization-level PATs instead of personal tokens

Example for GPM access:

- name: Maven settings with GPM access
  uses: whelk-io/maven-settings-xml-action@v22
  with:
    repositories: |
      [
        {
          "id": "github",
          "url": "https://maven.pkg.github.com/liquibase/*",
          "releases": {
            "enabled": "true"
          },
          "snapshots": {
            "enabled": "true"
          }
        }
      ]
    servers: |
      [
        {
          "id": "github",
          "username": "${{ github.actor }}",
          "password": "${{ env.LIQUIBOT_PAT_GPM_ACCESS }}"
        }
      ]

🛡️ Token Selection Strategy

Our approach to selecting tokens follows these principles:

Default to GITHUB_TOKEN when possible for its security and simplicity
Use GitHub App tokens for cross-repository operations
Limit PAT usage to only specialized cases where other token types don't suffice
Scope permissions explicitly for all token types
Separate tokens for different types of operations (deployment vs. reading)

This strategy helps us maintain security while ensuring our CI/CD workflows operate smoothly with appropriate permissions.

Unified Extension Automated Release (OSS & Commercial)

The extension-automated-release.yml workflow is a unified release automation for both OSS and commercial/secure Liquibase extensions. It automatically publishes extensions to Maven Central.

Supports:

OSS Extensions: BigQuery, Cache, Cassandra, CosmosDB, DB2i, FileChangelog, NoChangeLock, HanaDB, MaxDB, Modify Column, MSSQL, Oracle, PostgreSQL, Redshift, SQLFire, Teradata, Vertica, YugabyteDB, Hibernate, Parent POM
Commercial Extensions: BigQuery, Databricks, MongoDB, Azure, AWS

Triggering the Workflow

The workflow is called from orchestrator workflows in different repositories:

For OSS Extensions (liquibase repository):

name: Release Extensions
on:
  workflow_dispatch:
    inputs:
      version:
        description: 'Liquibase Version'
        required: true

jobs:
  automated-os-extensions-release:
    uses: liquibase/build-logic/.github/workflows/extension-automated-release.yml@main
    secrets: inherit
    with:
      version: ${{ inputs.version }}
      # Uses default OSS extension list

For Commercial/Secure Extensions (liquibase-pro repository):

name: Release Secure Extensions
on:
  workflow_dispatch:
    inputs:
      version:
        description: 'Liquibase Secure Version (e.g., 5.0.0, 5.0.1)'
        required: true

jobs:
  automated-secure-extensions-release:
    uses: liquibase/build-logic/.github/workflows/extension-automated-release.yml@main
    secrets: inherit
    with:
      version: ${{ inputs.version }}
      repositories: '["liquibase-commercial-bigquery","liquibase-commercial-databricks","liquibase-commercial-mongodb","liquibase-azure-extension","liquibase-aws-extension"]'

To manually trigger a release:

For OSS Extensions:

Navigate to the liquibase repository on GitHub
Go to Actions → Release Extensions
Click Run workflow
Enter the version number (e.g., 4.26.0)
Click Run workflow to start

For Commercial Extensions:

Navigate to the liquibase-pro repository on GitHub
Go to Actions → Release Secure Extensions
Click Run workflow
Enter the version number (e.g., 4.26.0)
Click Run workflow to start

Workflow Inputs

version (required): Version to release in semantic versioning format (e.g., 4.26.0, 4.26.1)
repositories (optional): JSON array of repository names to release
- Default: ["liquibase-bigquery", "liquibase-databricks", "liquibase-mongodb", "liquibase-azure", "liquibase-aws"]
- Can be customized to release specific extensions only

Workflow Jobs

The workflow executes the following jobs in sequence:

1. check-security-vulnerabilities

Runs in parallel across all specified extension repositories
Checks for open Dependabot security alerts using GitHub API
Fails if any open security vulnerabilities are found
Uses matrix strategy with fail-fast: false to check all repositories

Log Messages:

INFO: "Checking repository: {repository}"
INFO: "Security vulnerabilities for {repository} are addressed."
ERROR: "Security vulnerabilities for {repository} are not addressed."

2. run-extensions-dependabot

Depends on: check-security-vulnerabilities
Installs and runs Dependabot CLI on each extension repository
Updates Maven dependencies automatically
Runs in parallel across all repositories

3. update-pom

Depends on: check-security-vulnerabilities
Updates extension versions to next SNAPSHOT
Updates liquibase.version property in pom.xml
Commits and pushes changes if modified
Configures Maven settings for both liquibase and liquibase-pro repositories

Important: Maven settings include access to both OSS and Pro packages for commercial extension dependencies.

4. release-draft-releases

Depends on: update-pom
Waits 180 seconds for artifacts to be available
Finds draft releases containing the specified version
Publishes draft releases (sets draft: false)
Tracks published releases

5. publish-to-central-portal

Depends on: release-draft-releases
Waits 120 seconds for releases to be fully available
Downloads artifacts from published GitHub releases (jar, pom, asc, md5, sha1)
Creates Maven repository layout bundles
Uploads to Sonatype Central Portal with AUTOMATIC publishing
Publishes to Maven Central (same as OSS extensions)

Artifact Types Downloaded:

.jar - Extension JAR file
.pom - Maven POM file
.asc - GPG signatures (code signing)
.md5 and .sha1 - Checksums

Requirements

Repository Structure

Each commercial extension repository must:

Have a LICENSE file (LICENSE, LICENSE.md, or LICENSE.txt) in the root
Include FSL license headers in Java source files
Follow Maven project structure with pom.xml
Have draft releases ready with signed artifacts

Secrets Required

The following secrets must be available in AWS Secrets Manager (/vault/liquibase):

LIQUIBASE_GITHUB_APP_ID - GitHub App ID for repository access
LIQUIBASE_GITHUB_APP_PRIVATE_KEY - GitHub App private key
LIQUIBOT_PAT_GPM_ACCESS - GitHub PAT for Maven Package access
SONATYPE_USERNAME - Sonatype Central Portal username
SONATYPE_TOKEN - Sonatype Central Portal token

Permissions

The workflow requires:

contents: write - For releasing and updating repositories
security-events: read - For checking Dependabot alerts
packages: write - For Maven package operations
id-token: write - For OIDC authentication with AWS

Troubleshooting

Common Issues

Issue: Security vulnerabilities not addressed

Cause: Open Dependabot alerts in repository
Solution: Review and fix Dependabot alerts before releasing
Check: GitHub repository → Security → Dependabot alerts

Issue: No artifacts found in release

Cause: Draft release doesn't contain artifacts for the specified version
Solution: Ensure draft release is created with proper version tag
Check: GitHub repository → Releases → Draft releases

Issue: Maven Central upload failed

Cause: Invalid credentials or artifact bundle structure
Solution: Verify SONATYPE_USERNAME and SONATYPE_TOKEN in vault
Check: Sonatype Central Portal deployment logs

Issue: POM update failed

Cause: Maven settings not configured or missing dependencies
Solution: Verify both liquibase and liquibase-pro repository access
Check: Ensure LIQUIBOT_PAT_GPM_ACCESS is valid

Release Process Flow

graph TB
    A[Manual Trigger from liquibase or liquibase-pro] --> B[Check Security Vulnerabilities]
    B --> C{All Extensions Clean?}
    C -->|No| D[Fail Workflow]
    C -->|Yes| E[Run Dependabot]
    E --> F[Update POMs]
    F --> G[Release Draft Releases]
    G --> H[Wait for Artifacts]
    H --> I[Download Artifacts]
    I --> J[Create Maven Bundles]
    J --> K[Upload to Central Portal]
    K --> L[Publish to Maven Central]
    L --> M[Archive Results]
    
    style A fill:#e1f5ff
    style L fill:#e8f5e9

Success Criteria

A successful release completes when:

✅ All security vulnerabilities addressed across all extensions
✅ POM versions updated and committed
✅ Draft releases published to GitHub
✅ Artifacts uploaded to Maven Central via Sonatype Central Portal
✅ Deployment IDs logged for tracking

Monitoring

GitHub Actions: View workflow runs in liquibase (OSS) or liquibase-pro (commercial) repositories
Maven Central: Track deployment status at https://central.sonatype.com/publishing/deployments
Artifacts: Published extensions artifact uploaded with deployment IDs
Logs: All jobs log INFO/WARNING/ERROR messages for easy debugging

Name		Name	Last commit message	Last commit date
Latest commit History 1,058 Commits
.github		.github
doc		doc
docker		docker
scripts		scripts
src		src
.gitignore		.gitignore
.trivyignore		.trivyignore
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
LICENSE.txt		LICENSE.txt
README.md		README.md

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

Liquibase Reusable Workflows

Introduction to GitHub Actions

About reusable workflows

Calling reusable workflows

Calling reusable workflows with parameters

🧩 Composite Action Wrappers

📦 Available Wrappers

🚀 Usage Example

🔄 How SHA Updates Work

⚠️ Important Notes

Example Build/Test/Release Extension Workflow

Vulnerability Scanning

Usage

Inputs

Outputs

Suppressing False Positives

Scripts

Release Notes Aggregation

Operating modes

Usage

Inputs

Auth

Convention dependency

Completeness invariant

Security

Requirements

pom.xml

Jacoco

Surefire

Artifacts

Maven release

Version Bumping after Release

Liquibase Test Harness

Docker Databases

Requirements

Liquibase test (unit & integration tests) + Sonar

Configuration

Parent pom.xml

modules with integration tests (pom.xml)

Modules without integration tests (pom.xml)

Coverage module (pom.xml)

Releasing a new version of build-logic

🔑 GitHub Tokens Strategy

🔒 Default GITHUB_TOKEN

When to use:

Security benefits:

Example:

🔐 GitHub App Tokens

When to use:

Security benefits:

Example:

🪪 Personal Access Tokens (PATs)

When to use:

Security considerations:

Example for GPM access:

🛡️ Token Selection Strategy

Unified Extension Automated Release (OSS & Commercial)

Triggering the Workflow

Workflow Inputs

Workflow Jobs

1. check-security-vulnerabilities

2. run-extensions-dependabot

3. update-pom

4. release-draft-releases

5. publish-to-central-portal

Requirements

Repository Structure

Secrets Required

Permissions

Troubleshooting

Common Issues

Release Process Flow

Success Criteria

Monitoring

About