GitHub Actions Workflow Setup

If you don’t want to install Liquibase locally on your laptop or use a remote host that will run the software for you, you can try the Liquibase GitHub Actions workflow.

GitHub Actions is a way to automate, customize, and execute your software development workflows in a repository. You can create and share actions to perform any job, including CI/CD, and combine actions in a customized workflow.

  • A workflow is an automated procedure that you add to your repository. Workflows are made up of one or more jobs and can be scheduled or triggered by an event. The workflow can be used to build, test, package, release, or deploy a project on GitHub.
  • A job is a set of steps that is executed on the same runner.

Note: For more information about GitHub Actions, see Introduction to GitHub Actions.

Prerequisites

Ensure that you have a GitHub account.

Note: For more information on how to create a GitHub account, see Signing Up for GitHub.

Using the Liquibase GitHub Action plugin

Using GitHub Actions, you can set the type of VM instance you want to run and the actions you want to perform during a job in a workflow.

Liquibase GitHub Action is the official Liquibase plugin for GitHub Actions. The plugin launches a Docker container with Liquibase tools on an ephemeral server hosted at GitHub. It allows you to automate and execute your workflows in a repository and run Liquibase commands. You can use the Liquibase GitHub Actions example repository with the setup workflows. This repository contains a README file with instructions to follow, Liquibase projects, and an H2 database with GitHub Actions workflows for the following setups:

  • Liquibase Command Line Interface (CLI)
  • Liquibase Maven commands with Spring Boot
  • Liquibase Gradle commands
  • Liquibase NodeJS commands
  • Liquibase running in Docker

There are corresponding files for each project in the repository:

Project Folder Files

Liquibase CLI commands

example/changelogs

The changelog files

Gradle

extra/Gradle_h2

The build.gradle and changelog files

Maven

extra/SalesManager_h2_version

The pom.xml and application.properties Spring Boot class Java files

Docker

extra/Docker

The changelog file

NodeJS extra/NodeJS The .js configuration files

The plugin supports the following Liquibase commands for automation:

  • update
  • updateSQL
  • updateCount
  • tag
  • updateToTag
  • rollback
  • rollbackCount
  • rollbackToDate
  • futureRollbackSQL
  • status
  • history
  • diff

Running Liquibase GitHub Actions

The steps in this section are based on the example files and an H2 database.

Tip: If you want to try GitHub Actions with your changelog and database, you can make a pull request against the liquibase-github-action repository with your operations, changelog, database username, password, and JDBC URL. To use the official Liquibase GitHub Action in your project, add a new uses: tag to your workflow YAML file that references liquibase/liquibase-github-action. Modify the with: tag to define the needed Liquibase command and other parameters. The README file provides two examples as well as the information on required and optional inputs.

  1. Fork the liquibase-github-action-example repository by selecting the Fork button at the upper-right corner of the liquibase-github-action-example page.
  2. Clone the liquibase-github-action-example repository by running the following in the CLI:
  3. git clone git@github.com:<YOURFORK>/liquibase/liquibase-github-action-example.git
  4. Create a new git branch for your changes:
  5. git checkout -b <your_branch_name>
  1. Edit example/changelogs/samplechangelog.h2.sql to add a new changeset. Replace yourname with a unique identifier:
  2. --changeset yourname:yourname1
    --rollback DROP TABLE yourname;
    CREATE TABLE yourname (
    id int primary key,
    name varchar(50) not null,
    )
  3. Add the database username, password, and URL to your GitHub Secrets. The values to use are in example/changelogs/configurationValues.txt. It is a good practice to protect your database credentials with Github Secrets, which will be used in the examples.
  4. Add, commit, and then push your changes to GitHub:
  5. git add example/changelogs/samplechangelog.h2.sql
    git commit -m "yourname: Adding new changeset for example"
    git push origin <your_branch_name>

Your commit triggers a build in GitHub and executes a Liquibase update.

To execute other commands, choose the command that you need from the list below. Then, update a code snippet example in the example.yml file located in .github/workflows before pushing your changes to GitHub.

To add and change a changelog or the liquibase.properties file, modify them in the repository and then commit your changes without installing the files locally.

Additional Examples

In addition to the default examples included in the example folder, the liquibase-github-action-example repository also contains other examples in the extra folder. There are non-Docker build systems such as Gradle, NodeJS, and Maven and a Docker example that does not use the official Liquibase action. While the official GitHub Action is the preferred way of implementing Docker-based workflows, there may be cases requiring custom container images from custom registries. The extra Docker example illustrates how you can do this.

You can find the corresponding GitHub Action workflow (.yml) files for all extra examples in the .github/workflows directory.

Troubleshooting

If your build fails due to a validation error, verify that your changeset’s author and id are unique in the changelog file. If Liquibase update fails, verify that your table name is unique in the changelog.

Note: For more information, see changelog and changeset.

Related Links