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.

Fork the liquibase-github-action-example repository by selecting the Fork button at the upper-right corner of the liquibase-github-action-example page.
Clone the liquibase-github-action-example repository by running the following in the CLI:

git clone git@github.com:<YOURFORK>/liquibase/liquibase-github-action-example.git

Create a new git branch for your changes:

git checkout -b <your_branch_name>

Edit example/changelogs/samplechangelog.h2.sql to add a new changeset. Replace yourname with a unique identifier:

--changeset yourname:yourname1
--rollback DROP TABLE yourname;
CREATE TABLE yourname (
id int primary key,
name varchar(50) not null,
)

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.
Add, commit, and then push your changes to GitHub:

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.

updateSQL

steps:
- uses: actions/checkout@v2
- uses: liquibase/liquibase-github-action@v1
  with:
	operation: 'updateSQL'
	classpath: 'example/changelogs'
	changeLogFile: 'samplechangelog.h2.sql'
	username: ${{ secrets.USERNAME }}
	password: ${{ secrets.PASSWORD }}
	url: ${{ secrets.URL }}

Note: For more information about the command, see the updateSQL command.

updateCount

steps:
- uses: actions/checkout@v2
- uses: liquibase/liquibase-github-action@v1
  with:
	operation: 'updateCount'
	classpath: 'example/changelogs'
	changeLogFile: 'samplechangelog.h2.sql'
	username: ${{ secrets.USERNAME }}
	password: ${{ secrets.PASSWORD }}
	url: ${{ secrets.URL }}
	count: 2

Note: For more information about the command, see the updateCount command.

tag

steps:
- uses: actions/checkout@v2
- uses: liquibase/liquibase-github-action@v1
  with:
	operation: 'tag'
	username: ${{ secrets.USERNAME }}
	password: ${{ secrets.PASSWORD }}
	url: ${{ secrets.URL }}
	tag: version1

Note: For more information about the command, see the tag command command.

updateToTag

steps:
- uses: actions/checkout@v2
- uses: liquibase/liquibase-github-action@v1
  with:
	operation: 'updateToTag'
	classpath: 'example/changelogs'
	changeLogFile: 'samplechangelog.h2.sql'
	username: ${{ secrets.USERNAME }}
	password: ${{ secrets.PASSWORD }}
	url: ${{ secrets.URL }}
	tag: version1

Note: For more information about the command, see the updateToTag command.

rollback

steps:
- uses: actions/checkout@v2
- uses: liquibase/liquibase-github-action@v1
  with:
	operation: 'rollback'
	classpath: 'example/changelogs'
	changeLogFile: 'samplechangelog.h2.sql'
	username: ${{ secrets.USERNAME }}
	password: ${{ secrets.PASSWORD }}
	url: ${{ secrets.URL }}
	tag: version1

Note: For more information about the command, see the rollback command.

rollbackCount

steps:
- uses: actions/checkout@v2
- uses: liquibase/liquibase-github-action@v1
  with:
	operation: 'rollbackCount'
	classpath: 'example/changelogs'
	changeLogFile: 'samplechangelog.h2.sql'
	username: ${{ secrets.USERNAME }}
	password: ${{ secrets.PASSWORD }}
	url: ${{ secrets.URL }}
	count: 2

Note: For more information about the command, see the rollbackCount command.

rollbackToDate

steps:
- uses: actions/checkout@v2
- uses: liquibase/liquibase-github-action@v1
  with:
	operation: 'rollbackToDate'
	classpath: 'example/changelogs'
	changeLogFile: 'samplechangelog.h2.sql'
	username: ${{ secrets.USERNAME }}
	password: ${{ secrets.PASSWORD }}
	url: ${{ secrets.URL }}
	date: 2020-05-07

Note: There are several ways to revert your changes with the rollbackToDate command. You can use the YYYY-MM-DD, HH:MM:SS, or YYYY-MM-DD'T'HH:MM:SS formats to specify date, time, or both. Also, you can specify the date or time only. For more information about the command, see the rollbackToDate command.

futureRollbackSQL

steps:
- uses: actions/checkout@v2
- uses: liquibase/liquibase-github-action@v1
  with:
	operation: 'futureRollbackSQL'
	classpath: 'example/changelogs'
	changeLogFile: 'samplechangelog.h2.sql'
	username: ${{ secrets.USERNAME }}
	password: ${{ secrets.PASSWORD }}
	url: ${{ secrets.URL }}

Note: For more information about the command, see the futureRollbackSQL command.

status

steps:
- uses: actions/checkout@v2
- uses: liquibase/liquibase-github-action@v1
  with:
	operation: 'status'
	classpath: 'example/changelogs'
	changeLogFile: 'samplechangelog.h2.sql'
	username: ${{ secrets.USERNAME }}
	password: ${{ secrets.PASSWORD }}
	url: ${{ secrets.URL }}

Note: For more information about the command, see the status --verbose command.

history

steps:
- uses: actions/checkout@v2
- uses: liquibase/liquibase-github-action@v1
  with:
	operation: 'history'
	classpath: 'example/changelogs'
	changeLogFile: 'samplechangelog.h2.sql'
	username: ${{ secrets.USERNAME }}
	password: ${{ secrets.PASSWORD }}
	url: ${{ secrets.URL }}

Note: For more information about the command, see the history command.

diff

steps:
- uses: actions/checkout@v2
- uses: liquibase/liquibase-github-action@v1
  with:
	operation: 'diff'
	classpath: 'example/changelogs'
	changeLogFile: 'samplechangelog.h2.sql'
	username: ${{ secrets.USERNAME }}
	password: ${{ secrets.PASSWORD }}
	url: ${{ secrets.URL }}
	referenceUrl: 'jdbc:oracle:thin:@<IP OR HOSTNAME>:<PORT>:<SERVICE NAME OR SID>'

Note: For more information about the command, see the diff command.

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.