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 |
|
The changelog files |
Gradle |
|
The |
Maven |
|
The |
Docker |
|
The changelog file |
NodeJS | extra/NodeJS
|
The .js configuration files |
The plugin supports the following Liquibase commands for automation:
- update
- update-sql
- update-count
- tag
- update-to-tag
- rollback
- rollback-count
- rollback-to-date
- future-rollback-sql
- 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: - Create a new git branch for your changes:
git clone git@github.com:<YOURFORK>/liquibase/liquibase-github-action-example.git
git checkout -b <your_branch_name>
- Edit
example/changelogs/samplechangelog.h2.sql
to add a new changeset. Replaceyourname
with a unique identifier: - 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:
--changeset yourname:yourname1
--rollback DROP TABLE yourname;
CREATE TABLE yourname (
id int primary key,
name varchar(50) not null,
)
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 it in the repository and commit the changes without installing the files locally.

update-sql
steps:
- uses: actions/checkout@v2
- uses: liquibase/liquibase-github-action@v1
with:
operation: 'update-sql'
classpath: 'example/changelogs'
changelog-file: 'samplechangelog.h2.sql'
username: ${{ secrets.USERNAME }}
password: ${{ secrets.PASSWORD }}
url: ${{ secrets.URL }}
Note: For more information about the command, see the update-sql command.

update-count
steps:
- uses: actions/checkout@v2
- uses: liquibase/liquibase-github-action@v1
with:
operation: 'update-count'
classpath: 'example/changelogs'
changelog-file: 'samplechangelog.h2.sql'
username: ${{ secrets.USERNAME }}
password: ${{ secrets.PASSWORD }}
url: ${{ secrets.URL }}
count: 2
Note: For more information about the command, see the update-count 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.

update-to-tag
steps:
- uses: actions/checkout@v2
- uses: liquibase/liquibase-github-action@v1
with:
operation: 'update-to-tag'
classpath: 'example/changelogs'
changelog-file: 'samplechangelog.h2.sql'
username: ${{ secrets.USERNAME }}
password: ${{ secrets.PASSWORD }}
url: ${{ secrets.URL }}
tag: version1
Note: For more information about the command, see the update-to-tag command.

rollback
steps:
- uses: actions/checkout@v2
- uses: liquibase/liquibase-github-action@v1
with:
operation: 'rollback'
classpath: 'example/changelogs'
changelog-file: '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.

rollback-count
steps:
- uses: actions/checkout@v2
- uses: liquibase/liquibase-github-action@v1
with:
operation: 'rollback-count'
classpath: 'example/changelogs'
changelog-file: 'samplechangelog.h2.sql'
username: ${{ secrets.USERNAME }}
password: ${{ secrets.PASSWORD }}
url: ${{ secrets.URL }}
count: 2
Note: For more information about the command, see the rollback-count command.

rollback-to-date
steps:
- uses: actions/checkout@v2
- uses: liquibase/liquibase-github-action@v1
with:
operation: 'rollback-to-date'
classpath: 'example/changelogs'
changelog-file: '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 rollback-to-date
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 rollback-to-date command.

future-rollback-sql
steps:
- uses: actions/checkout@v2
- uses: liquibase/liquibase-github-action@v1
with:
operation: 'future-rollback-sql'
classpath: 'example/changelogs'
changelog-file: 'samplechangelog.h2.sql'
username: ${{ secrets.USERNAME }}
password: ${{ secrets.PASSWORD }}
url: ${{ secrets.URL }}
Note: For more information about the command, see the future-rollback-sql command.

status
steps:
- uses: actions/checkout@v2
- uses: liquibase/liquibase-github-action@v1
with:
operation: 'status'
classpath: 'example/changelogs'
changelog-file: 'samplechangelog.h2.sql'
username: ${{ secrets.USERNAME }}
password: ${{ secrets.PASSWORD }}
url: ${{ secrets.URL }}
Note: For more information about the command, see the status command.

history
steps:
- uses: actions/checkout@v2
- uses: liquibase/liquibase-github-action@v1
with:
operation: 'history'
classpath: 'example/changelogs'
changelog-file: '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'
changelog-file: '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.
Note: For more information, see Working with changelogs and Changelog Formats.