GitHub Actions for Atlas

This repository contains GitHub Actions for working with Atlas.

If you are looking for the old TypeScript-based action, please see the old README.

To learn more about the recommended way to build workflows, read our guide on Modern CI/CD for Databases.

Actions

Action	Description
ariga/setup-atlas	Setup the Atlas CLI and optionally login to Atlas Cloud
ariga/atlas-action/migrate/push	Push migrations to Atlas Registry
ariga/atlas-action/migrate/lint	Lint migrations (required `atlas login` )
ariga/atlas-action/migrate/apply	Apply migrations to a database
ariga/atlas-action/migrate/down	Revert migrations to a database
ariga/atlas-action/migrate/test	Test migrations on a database
ariga/atlas-action/schema/test	Test schema on a database
ariga/atlas-action/schema/push	Push a schema to Atlas Registry
ariga/atlas-action/schema/plan	Plan a declarative migration for a schema transition
ariga/atlas-action/schema/plan/approve	Approve a declarative migration plan
ariga/atlas-action/schema/apply	Apply a declarative migrations to a database

Examples

The Atlas GitHub Actions can be composed into workflows to create CI/CD pipelines for your database schema. Workflows will normally begin with the setup-atlas action, which will install the Atlas CLI and optionally login to Atlas Cloud. Followed by whatever actions you need to run, such as migrate lint or migrate apply.

Pre-requisites

The following examples require you to have an Atlas Cloud account and a push an initial version of your migration directory.

To create an account, first download the Atlas CLI (on Linux/macOS):

curl -sSL https://atlasgo.io/install | sh

For more installation options, see the documentation.

Then, create an account by running the following command and following the instructions:

atlas login

After logging in, push your migration directory to Atlas Cloud:

atlas migrate push --dev-url docker://mysql/8/dev --dir-name my-project

For a more detailed guide, see the documentation.

Finally, you will need an API token to use the Atlas GitHub Actions. To create a token, see the docs.

Continuous Integration and Delivery

This example workflow shows how to configure a CI/CD pipeline for your database schema. The workflow will verify the safety of your schema changes when in a pull request and push migrations to Atlas Cloud when merged into the main branch.

Quick Setup: Using the `gh` CLI

If you have the gh CLI installed, you can use the following command to setup a workflow for your repository:

gh extension install ariga/gh-atlas
gh auth refresh -s write:packages,workflow
gh atlas init-action

This will create a pull request with a workflow that will run migrate lint on pull requests and migrate push on the main branch. You can customize the workflow by editing the generated .github/workflows/atlas-ci.yaml file.

Manual Setup: Create a workflow

Create a new file named .github/workflows/atlas.yaml with the following contents:

name: Atlas CI/CD
on:
  push:
    branches:
      - master # Use your main branch here.
  pull_request:
    paths:
      - 'migrations/*' # Use the path to your migration directory here.
# Permissions to write comments on the pull request.
permissions:
  contents: read
  pull-requests: write
jobs:
  atlas:
    services:
      # Spin up a mysql:8 container to be used as the dev-database for analysis.
      mysql:
        image: mysql:8
        env:
          MYSQL_DATABASE: dev
          MYSQL_ROOT_PASSWORD: pass
        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
    env:
      GITHUB_TOKEN: ${{ github.token }}
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0
      - uses: ariga/setup-atlas@v0
        with:
          cloud-token: ${{ secrets.ATLAS_TOKEN }}
      - uses: ariga/atlas-action/migrate/lint@v1
        with:
          dir: 'file://migrations'
          dir-name: 'my-project' # The name of the project in Atlas Cloud
          dev-url: "mysql://root:pass@localhost:3306/dev"
      - uses: ariga/atlas-action/migrate/push@v1
        if: github.ref == 'refs/heads/master'
        with:
          dir: 'file://migrations'
          dir-name: 'my-project' 
          dev-url: 'mysql://root:pass@localhost:3306/dev' # Use the service name "mysql" as the hostname

This example uses a MySQL database, but you can use any database supported by Atlas.
For more examples, see the documentation.

Continuous Deployment

This example workflow shows how to configure a continuous deployment pipeline for your database schema. The workflow will apply migrations on the target database whenever a new commit is pushed to the main branch.

name: Atlas Continuous Deployment
on:
  push:
    branches:
      - master
jobs:
  apply:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0
      - uses: ariga/setup-atlas@v0
        with:
          cloud-token: ${{ secrets.ATLAS_TOKEN }}
      - uses: ariga/atlas-action/migrate/apply@v1
        with:
          url: 'mysql://user:${{ secrets.DB_PASSWORD }}@db.hostname.io:3306/db'
          dir: 'atlas://my-project' # A directory stored in Atlas Cloud, use ?tag=<tag> to specify a tag

This example workflow shows how to configure a deployment pipeline for your database schema. This workflow will pull the most recent version of your migration directory from Atlas Cloud and apply it to the target database.

For more examples, see the documentation.

API

`ariga/setup-atlas`

Setup the Atlas CLI and optionally login to Atlas Cloud.

Inputs

cloud-token - (Optional) The Atlas Cloud token to use for authentication. To create a cloud token see the docs.
version - (Optional) The version of the Atlas CLI to install. Defaults to the latest version.

`ariga/atlas-action/migrate/push`

Push the current version of your migration directory to Atlas Cloud.

Inputs

All inputs are optional as they may be specified in the Atlas configuration file.

dir - The URL of the migration directory to push. For example: file://migrations. Read more about Atlas URLs.
dir-name - The name (slug) of the project in Atlas Cloud.
dev-url - The URL of the dev-database to use for analysis. For example: mysql://root:pass@localhost:3306/dev. Read more about dev-databases.
tag - The tag to apply to the pushed migration directory. By default the current git commit hash is used.
latest - Whether to implicitly push the "latest" tag. True by default.
config - The path to the Atlas configuration file. By default, Atlas will look for a file named atlas.hcl in the current directory. For example, file://config/atlas.hcl. Learn more about Atlas configuration files.
env - The environment to use from the Atlas configuration file. For example, dev.
vars - Stringify JSON object containing variables to be used inside the Atlas configuration file. For example: '{"var1": "value1", "var2": "value2"}'.
working-directory - The working directory to run from. Defaults to project root.

Outputs

url - The URL of the migration directory in Atlas Cloud, containing an ERD visualization of the schema.

`ariga/atlas-action/migrate/lint` (Required `atlas login`)

Lint migration changes with Atlas

Inputs

All inputs are optional as they may be specified in the Atlas configuration file.

dir - The URL of the migration directory to lint. For example: file://migrations. Read more about Atlas URLs.
dir-name - The name (slug) of the project in Atlas Cloud.
tag - The tag of migrations to used as base for linting. By default, the latest tag is used.
dev-url - The URL of the dev-database to use for analysis. For example: mysql://root:pass@localhost:3306/dev. Read more about dev-databases.
config - The path to the Atlas configuration file. By default, Atlas will look for a file named atlas.hcl in the current directory. For example, file://config/atlas.hcl. Learn more about Atlas configuration files.
env - The environment to use from the Atlas configuration file. For example, dev.
vars - Stringify JSON object containing variables to be used inside the Atlas configuration file. For example: '{"var1": "value1", "var2": "value2"}'.
working-directory - The working directory to run from. Defaults to project root.

Outputs

url - The URL of the CI report in Atlas Cloud, containing an ERD visualization and analysis of the schema migrations.

`ariga/atlas-action/migrate/apply`

Apply migrations to a database.

Inputs

All inputs are optional as they may be specified in the Atlas configuration file.

url - The URL of the target database. For example: mysql://root:pass@localhost:3306/prod.
dir - The URL of the migration directory to apply. For example: atlas://dir-name for cloud based directories or file://migrations for local ones.
config - The URL of the Atlas configuration file. By default, Atlas will look for a file named atlas.hcl in the current directory. For example, file://config/atlas.hcl. Learn more about Atlas configuration files.
env - The environment to use from the Atlas configuration file. For example, dev.
dry-run - Print SQL without executing it. Defaults to false
vars - Stringify JSON object containing variables to be used inside the Atlas configuration file. For example: '{"var1": "value1", "var2": "value2"}'.
working-directory - The working directory to run from. Defaults to project root.

Outputs

current - The current version of the database. (before applying migrations)
target - The target version of the database.
pending_count - The number of migrations that will be applied.
applied_count - The number of migrations that were applied.

`ariga/atlas-action/migrate/down`

Revert migrations to a database.

Inputs

All inputs are optional as they may be specified in the Atlas configuration file.

url - The URL of the target database. For example: mysql://root:pass@localhost:3306/dev.
dir - The URL of the migration directory to apply. For example: atlas://dir-name for cloud based directories or file://migrations for local ones.
config - The URL of the Atlas configuration file. By default, Atlas will look for a file named atlas.hcl in the current directory. For example, file://config/atlas.hcl. Learn more about Atlas configuration files.
env - The environment to use from the Atlas configuration file. For example, dev.
amount - The amount of applied migrations to revert, defaults to 1.
to-version - To which version to revert.
to-tag - To which tag to revert.
wait-timeout - Time after which no other retry attempt is made and the action exits. If not set, only one attempt is made.
wait-interval - Time in seconds between different migrate down attempts, useful when waiting for plan approval, defaults to 1s.
vars - Stringify JSON object containing variables to be used inside the Atlas configuration file. For example: '{"var1": "value1", "var2": "value2"}'.
working-directory - The working directory to run from. Defaults to project root.

Outputs

current - The current version of the database. (before applying migrations)
target - The target version of the database.
pending_count - The number of migrations that will be applied.
reverted_count - The number of migrations that were reverted.
url - The URL of the plan to review and approve / reject.

`ariga/atlas-action/migrate/test`

Run schema migration tests. Read more in Atlas website.

Inputs

All inputs are optional as they may be specified in the Atlas configuration file.

dev-url - The URL of the dev-database to use for analysis. For example: mysql://root:pass@localhost:3306/dev. Read more about dev-databases.
dir - The URL of the migration directory to apply. For example: atlas://dir-name for cloud based directories or file://migrations for local ones.
run - Filter tests to run by regexp. For example, ^test_.* will only run tests that start with test_. Default is to run all tests.
config - The URL of the Atlas configuration file. By default, Atlas will look for a file named atlas.hcl in the current directory. For example, file://config/atlas.hcl. Learn more about Atlas configuration files.
env - The environment to use from the Atlas configuration file. For example, dev.
vars - Stringify JSON object containing variables to be used inside the Atlas configuration file. For example: '{"var1": "value1", "var2": "value2"}'.
working-directory - The working directory to run from. Defaults to project root.

`ariga/atlas-action/schema/test`

Run schema tests on the desired schema. Read more in Atlas website.

Inputs

All inputs are optional as they may be specified in the Atlas configuration file.

dev-url - The URL of the dev-database to use for analysis. For example: mysql://root:pass@localhost:3306/dev. Read more about dev-databases.
url - The desired schema URL(s) to test. For Example: file://schema.hcl
run - Filter tests to run by regexp. For example, ^test_.* will only run tests that start with test_. Default is to run all tests.
config - The URL of the Atlas configuration file. By default, Atlas will look for a file named atlas.hcl in the current directory. For example, file://config/atlas.hcl. Learn more about Atlas configuration files.
env - The environment to use from the Atlas configuration file. For example, dev.
vars - Stringify JSON object containing variables to be used inside the Atlas configuration file. For example: '{"var1": "value1", "var2": "value2"}'.
working-directory - The working directory to run from. Defaults to project root.

`ariga/atlas-action/schema/apply`

Apply a declarative migrations to a database.

Inputs

to - The URL(s) of the desired schema state.
url - The URL of the target database. For example: mysql://root:pass@localhost:3306/prod.
plan - Optional plan file to use for applying the migrations. For example: atlas://<schema>/plans/<id>.
dry-run - Print SQL (and optional analysis) without executing it. Either true or false. Defaults to false.
auto-approve - Automatically approve and apply changes. Either true or false. Defaults to false.
dev-url - The URL of the dev-database to use for analysis. For example: mysql://root:pass@localhost:3306/dev. Read more about dev-databases.
schema - The database schema(s). For example: public.
config - The URL of the Atlas configuration file. By default, Atlas will look for a file named atlas.hcl in the current directory. For example, file://config/atlas.hcl. Learn more about Atlas configuration files.
env - The environment to use from the Atlas configuration file. For example, dev.
vars - Stringify JSON object containing variables to be used inside the Atlas configuration file. For example: '{"var1": "value1", "var2": "value2"}'.
working-directory - The working directory to run from. Defaults to project root.

Outputs

error - The error message if the action fails.

`ariga/atlas-action/schema/push`

Push a schema to Atlas Registry with an optional tag.

Inputs

schema-name - The name (slug) of the schema repository in Atlas Registry.
url - Desired schema URL(s) to push. For example: file://schema.hcl.
tag - The tag to apply to the pushed schema. By default, the current git commit hash is used.
latest - Whether to implicitly push the latest tag. True by default.
dev-url - The URL of the dev-database to use for analysis. For example: mysql://root:pass@localhost:3306/dev. Read more about dev-databases.
schema - The database schema(s) to push. For example: public.
config - The URL of the Atlas configuration file. By default, Atlas will look for a file named atlas.hcl in the current directory. For example, file://config/atlas.hcl. Learn more about Atlas configuration files.
env - The environment to use from the Atlas configuration file. For example, dev.
vars - Stringify JSON object containing variables to be used inside the Atlas configuration file. For example: '{"var1": "value1", "var2": "value2"}'.
working-directory - The working directory to run from. Defaults to project root.

Outputs

slug - The slug of the schema repository in Atlas Registry.
link - The URL of the schema in Atlas Registry.
url - The URL of the pushed schema version in Atlas format. For example, atlas://app.

`ariga/atlas-action/schema/plan`

Plan a declarative migration for a schema transition.

Inputs

schema-name - The name (slug) of the schema repository in Atlas Registry.
from - URL(s) of the current schema state to transition from.
to - URL(s) of the desired schema state to transition to.
name - Optional name for the plan. If not provided, a default plan is generated by Atlas.
dev-url - The URL of the dev-database to use for analysis. For example: mysql://root:pass@localhost:3306/dev. Read more about dev-databases.
schema - The database schema(s). For example: public.
config - The URL of the Atlas configuration file. By default, Atlas will look for a file named atlas.hcl in the current directory. For example, file://config/atlas.hcl. Learn more about Atlas configuration files.
env - The environment to use from the Atlas configuration file. For example, dev.
vars - Stringify JSON object containing variables to be used inside the Atlas configuration file. For example: '{"var1": "value1", "var2": "value2"}'.
working-directory - The working directory to run from. Defaults to project root.

Outputs

plan - The URL of the generated plan in Atlas format. For example, atlas://app/plans/123.
link - The URL of the plan in Atlas Registry.
status - The status of the plan. For example, PENDING or APPROVED.

`ariga/atlas-action/schema/plan/approve`

Approve a declarative migration plan.

Inputs

schema-name - The name (slug) of the schema repository in Atlas Registry.
from - URL(s) of the current schema state to transition from.
to - URL(s) of the desired schema state to transition to.
plan - Optional URL of the plan to be approved. For example, atlas://<schema>/plans/<id>. By default, Atlas searches in the registry for a plan corresponding to the given schema transition and approves it (typically, this plan is created during the PR stage). If multiple plans are found, an error will be thrown.
dev-url - The URL of the dev-database to use for analysis. For example: mysql://root:pass@localhost:3306/dev. Read more about dev-databases.
config - The URL of the Atlas configuration file. By default, Atlas will look for a file named atlas.hcl in the current directory. For example, file://config/atlas.hcl. Learn more about Atlas configuration files.
env - The environment to use from the Atlas configuration file. For example, dev.
vars - Stringify JSON object containing variables to be used inside the Atlas configuration file. For example: '{"var1": "value1", "var2": "value2"}'.
working-directory - The working directory to run from. Defaults to project root.

Outputs

plan - The URL of the generated plan in Atlas format. For example, atlas://app/plans/123.
link - The URL of the plan in Atlas Registry.
status - The status of the plan. For example, PENDING or APPROVED.

Legal

The source code for this GitHub Action is released under the Apache 2.0 License, see LICENSE.

This action downloads a binary version of Atlas which is distributed under the Ariga EULA.

Files

README.md

Latest commit

History

README.md

File metadata and controls

GitHub Actions for Atlas

Actions

Examples

Pre-requisites

Continuous Integration and Delivery

Quick Setup: Using the gh CLI

Manual Setup: Create a workflow

Continuous Deployment

API

ariga/setup-atlas

Inputs

ariga/atlas-action/migrate/push

Inputs

Outputs

ariga/atlas-action/migrate/lint (Required atlas login)

Inputs

Outputs

ariga/atlas-action/migrate/apply

Inputs

Outputs

ariga/atlas-action/migrate/down

Inputs

Outputs

ariga/atlas-action/migrate/test

Inputs

ariga/atlas-action/schema/test

Inputs

ariga/atlas-action/schema/apply

Inputs

Outputs

ariga/atlas-action/schema/push

Inputs

Outputs

ariga/atlas-action/schema/plan

Inputs

Outputs

ariga/atlas-action/schema/plan/approve

Inputs

Outputs

Legal

Quick Setup: Using the `gh` CLI

`ariga/setup-atlas`

`ariga/atlas-action/migrate/push`

`ariga/atlas-action/migrate/lint` (Required `atlas login`)

`ariga/atlas-action/migrate/apply`

`ariga/atlas-action/migrate/down`

`ariga/atlas-action/migrate/test`

`ariga/atlas-action/schema/test`

`ariga/atlas-action/schema/apply`

`ariga/atlas-action/schema/push`

`ariga/atlas-action/schema/plan`

`ariga/atlas-action/schema/plan/approve`