Skip to main content

GitHub Actions

GitHub Actions is a popular CI/CD product from GitHub. With GitHub Actions, users can easily define workflows that are triggered in various lifecycle events related to a Git repository. For example, many teams configure GitHub actions to run all unit tests in a repository on each change that is committed to a repository.

One of the powerful features of GitHub Actions is its extensibility: it is very easy to package a piece of functionality as a module (called an "action") that can later be re-used by many projects.

Atlas provides a number of GitHub Actions that can be used to automate database schema management tasks.

ActionUse Case
ariga/atlas-actionCI for schema changes
ariga/atlas-sync-actionSync your migration directory to Atlas Cloud (atlasgo.cloud)
ariga/atlas-deploy-actionDeploy versioned migrations from GitHub Actions
ariga/setup-atlasInstall Atlas from a GitHub Actions workflow

ariga/atlas-action (CI)​

Teams using GitHub that wish to ensure all changes to their database schema are safe can use the atlas-action GitHub Action.

This action is used for linting migration directories using the atlas migrate lint command. This command validates and analyzes the contents of migration directories and generates insights and diagnostics on the selected changes:

  • Ensure the migration history can be replayed from any point at time.
  • Protect from unexpected history changes when concurrent migrations are written to the migration directory by multiple team members. Read more about the consistency checks in the section below.
  • Detect whether destructive or irreversible changes have been made or whether they are dependent on tables'
    contents and can cause a migration failure.

Supported directory formats​

This action supports analyzing migration directories in formats accepted by different schema migration tools:

Usage​

Add .github/workflows/atlas-ci.yaml to your repo with the following contents:

name: Atlas CI
on:
  # Run whenever code is changed in the master branch,
  # change this to your root branch.
  push:
    branches:
      - master
  # Run on PRs where something changed under the `path/to/migration/dir/` directory.
  pull_request:
    paths:
      - 'path/to/migration/dir/*'
jobs:
  lint:
    services:
      # Spin up a mysql:8 container to be used as the dev-database for analysis.
      mysql:
        image: mysql:8
        env:
          MYSQL_ROOT_PASSWORD: pass
          MYSQL_DATABASE: test
        ports:
          - "3306:3306"
        options: >-
          --health-cmd "mysqladmin ping -ppass"
          --health-interval 10s
          --health-start-period 10s
          --health-timeout 5s
          --health-retries 10
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3.0.1
        with:
          fetch-depth: 0 # Mandatory unless "latest" is set below.
      - uses: ariga/atlas-action@v0
        with:
          dir: path/to/migrations
          dir-format: atlas # Or: golang-migrate, liquibase, flyway, goose, dbmate
          dev-url: mysql://root:pass@localhost:3306/test

Configuration​

Configure the action by passing input parameters in the with: block.

dir​

Sets the directory that contains the migration scripts to analyze.

dir-format​

Sets the format of the migration directory. Options: atlas (default), golang-migrate, goose or dbmate, flyway, liquibase.

dev-url​

The URL of the dev-database to use for analysis.

latest​

Use the latest mode to decide which files to analyze. By default, Atlas will use git-base to analyze any files that are present in the diff between the base branch and the current.

Unless this option is set, the base branch (master/main/etc) must be checked out locally or you will see an error such as:

Atlas failed with code 1: Error: git diff: exit status 128

The full list of input options can be found in action.yml.

ariga/atlas-deploy-action​

You can use ariga/atlas-deploy-action to deploy migrations to your database directly from GitHub Actions.

info

Atlas needs network access to your database to deploy migrations, so make sure your database is either publicly accessible or that you have otherwise enabled network access to it from your GitHub Actions runners.

This action supports two workflows:

  • Local - the migration directory is checked in to the repository.
  • Cloud - the migration directory is connected to Atlas Cloud. Runs are reported to your Atlas Cloud account.

Examples​

Notice that the following examples rely on a DATABASE_URL secret being set in your repository.

To learn how to set secrets, read GitHub's documentation.

The DATABASE_URL secret should be set to the URL of your database, for examples please see Atlas URL formats.

Local​

name: Deploy Database Migrations
on:
  push:
    branches:
      - master
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Deploy Atlas Migrations
        uses: ariga/atlas-deploy-action@v0
        with:
          url: ${{ secrets.DATABASE_URL }}
          dir: path/to/migrations

Deploy from Cloud​

name: Deploy Database Migrations
on:
  push:
    branches:
      - master
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Deploy Atlas Migrations
        uses: ariga/atlas-deploy-action@v0
        with:
          url: ${{ secrets.DATABASE_URL }}
          cloud-token: ${{ secrets.ATLAS_CLOUD_TOKEN }}
          cloud-dir: hello # replace with your directory name

Reference​

Inputs​

  • url: URL to target database (should be passed as a secret). (Required)
  • dir: Local path of the migration directory in the repository. (Optional)
  • cloud-token: Token for using Atlas Cloud (should be passed as a secret). (Optional)
  • cloud-dir: Name of the migration directory in the cloud. (Must be set if cloud-token is set)
  • cloud-tag: Tag of the migration version in the cloud. (Optional)

Note: Either dir or cloud-dir must be set. If both are provided, an error will be thrown.

Outputs​

  • error: Error message if any.
  • current: Current migration version.
  • target: Target migration version.
  • pending_count: Number of pending migrations.
  • applied_count: Number of applied migrations.

ariga/atlas-sync-action​

You can use ariga/atlas-sync-action to sync your migration directory from your GitHub repository to Atlas Cloud.

Use this action in your workflow to sync your migration directory to Atlas Cloud. It is highly recommended that you only run this action on the main branch of your repository, as its purpose is to persist the desired state of your migration directory.

To use this action, you must first have a Bot Token with permissions to write to your account. To learn how to create tokens, read Atlas Cloud Bots.

Example​

name: Sync Atlas Migrations
on:
  push:
    branches:
      - master # Only run on our main branch
jobs:
  sync:
    runs-on: ubuntu-latest
    services:
      # Spin up a mysql:8 container to be used as the dev-database for analysis.
      mysql:
        image: mysql:8
        env:
          MYSQL_ROOT_PASSWORD: pass
          MYSQL_DATABASE: test
        options: >-
          --health-cmd "mysqladmin ping -ppass"
          --health-interval 10s
          --health-start-period 10s
          --health-timeout 5s
          --health-retries 10
    steps:
      - uses: actions/checkout@v3
      - uses: ariga/atlas-sync-action@v0
        with:
          name: dir_name
          dir: path/to/migrations
          dev-url: 'mysql://root:pass@mysql:3306/dev'
          cloud-token: ${{ secrets.ATLAS_CLOUD_TOKEN }}

Reference​

Configure this action with the following inputs:

dir​

Required The path to the directory containing your migrations.

driver​

Required The database driver to use. One of: mysql, postgres, sqlite.

cloud-token​

Required The Atlas Cloud token to use for authentication.

ariga/setup-atlas​

The ariga/setup-atlas action can be used to install Atlas from a GitHub Actions workflow.

This is useful if your team wants to use Atlas via scripts or when you want to use features that are not exposed by other actions.

Example​

name: Deploy schema changes
run-name: I'm using Atlas 🚀
on: [push]
jobs:
  use-atlas:
    runs-on: ubuntu-latest
    steps:
      - uses: ariga/setup-atlas@master
      - run: atlas version
      # - run: atlas schema apply ...

Reference​

The action supports the version input:

version​

By default, the latest version of Atlas is being used. If you want to lock a specific version of Atlas, you can do so by specifing the version parameter.