-
Notifications
You must be signed in to change notification settings - Fork 6
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
2 changed files
with
262 additions
and
73 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,61 +1,57 @@ | ||
| # atlas-action | ||
| # GitHub Actions for Atlas | ||
|
|
||
| A GitHub Action for [Atlas](https://github.com/ariga/atlas). | ||
| This repository contains GitHub Actions for working with [Atlas](https://atlasgo.io). | ||
|
|
||
| This action is used for [linting migration directories](https://atlasgo.io/versioned/lint) | ||
| 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: | ||
| If you are looking for the old TypeScript-based action, please see the old [README](doc/typescript-action.md). | ||
|
|
||
| * 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. | ||
| * Detect whether destructive or irreversible changes have been made or whether they are dependent on tables' | ||
| contents and can cause a migration failure. | ||
| To learn more about the recommended way to build workflows, read our guide on | ||
| [Modern CI/CD for Databases](https://atlasgo.io/guides/modern-database-ci-cd). | ||
|
|
||
| ### Supported directory formats | ||
| ## Actions | ||
|
|
||
| This action supports analyzing migration directories in formats | ||
| accepted by different schema migration tools: | ||
| * [Atlas](https://atlasgo.io) | ||
| * [golang-migrate](https://github.com/golang-migrate/migrate) | ||
| * [goose](https://github.com/pressly/goose) | ||
| * [dbmate](https://github.com/amacneil/dbmate) | ||
| * [Flyway](https://flywaydb.org/) | ||
| * [Liquibase](https://www.liquibase.org/) | ||
| | Action | Description | | ||
| |----------------------------------------------------|---------------------------------------------------------| | ||
| | [ariga/setup-atlas](#setup-atlas) | Setup the Atlas CLI and optionally login to Atlas Cloud | | ||
| | [ariga/atlas-action/migrate/push](#migrate-push) | Push migrations to Atlas Cloud | | ||
| | [ariga/atlas-action/migrate/lint](#migrate-lint) | Lint migrations | | ||
| | [ariga/atlas-action/migrate/apply](#migrate-apply) | Apply migrations to a database | | ||
|
|
||
| ### Usage | ||
| ## Example | ||
|
|
||
| Add `.github/workflows/atlas-ci.yaml` to your repo with the following contents: | ||
| 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`. | ||
|
|
||
| ### 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. | ||
|
|
||
| ```yaml | ||
| name: Atlas CI | ||
| name: Atlas CI/CD | ||
| 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/*' | ||
| - 'migrations/*' | ||
| # Permissions to write comments on the pull request. | ||
| permissions: | ||
| contents: read | ||
| pull-requests: write | ||
| jobs: | ||
| lint: | ||
| atlas: | ||
| services: | ||
| # Spin up a mysql:8.0.29 container to be used as the dev-database for analysis. | ||
| # If you use a different database, change the image configuration and update | ||
| # the `dev-url` configuration below. | ||
| # Spin up a mysql:8 container to be used as the dev-database for analysis. | ||
| mysql: | ||
| image: mysql:8.0.29 | ||
| image: mysql:8 | ||
| env: | ||
| MYSQL_DATABASE: dev | ||
| MYSQL_ROOT_PASSWORD: pass | ||
| MYSQL_DATABASE: test | ||
| ports: | ||
| - "3306:3306" | ||
| - 3306:3306 | ||
| options: >- | ||
| --health-cmd "mysqladmin ping -ppass" | ||
| --health-interval 10s | ||
|
|
@@ -64,72 +60,128 @@ jobs: | |
| --health-retries 10 | ||
| runs-on: ubuntu-latest | ||
| steps: | ||
| - uses: actions/[email protected] | ||
| - uses: actions/checkout@v3 | ||
| with: | ||
| fetch-depth: 0 | ||
| - uses: ariga/setup-atlas@v0 | ||
| with: | ||
| cloud-token: ${{ secrets.ATLAS_CLOUD_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@mysql:3306/dev' # Use the service name "mysql" as the hostname | ||
| cloud-token: ${{ secrets.ATLAS_CLOUD_TOKEN }} | ||
| ``` | ||
| This example uses a MySQL database, but you can use any database supported by Atlas. | ||
| For more examples, see the [documentation](https://atlasgo.io/integrations/github-actions). | ||
| ### 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. | ||
| ```yaml | ||
| 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: | ||
| fetch-depth: 0 # Mandatory unless "latest" is set below. | ||
| - uses: ariga/atlas-action@v0 | ||
| cloud-token: ${{ secrets.ATLAS_CLOUD_TOKEN }} | ||
| - uses: ariga/atlas-action/migrate/apply@v1 | ||
| with: | ||
| dir: path/to/migrations | ||
| dir-format: atlas | ||
| dev-url: mysql://root:pass@localhost:3306/test | ||
| url: 'mysql://user:${{ secrets.DB_PASSWORD }}@db.hostname.io:3306/db' | ||
| dir: 'atlas://my-project:latest' # A directory stored in Atlas Cloud | ||
| ``` | ||
| ### Configuration | ||
| 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. | ||
| Configure the action by passing input parameters in the `with:` block. | ||
| For more examples, see the [documentation](https://atlasgo.io/integrations/github-actions). | ||
| #### `config-path` | ||
| ## API | ||
| Sets the path to the Atlas configuration file. By default, Atlas will | ||
| look for a file named `atlas.hcl` in the current directory. | ||
| ### `ariga/setup-atlas` | ||
|
|
||
| #### `config-env` | ||
| Setup the Atlas CLI and optionally login to Atlas Cloud. | ||
|
|
||
| Sets the environment to use from the Atlas configuration file. | ||
| #### Inputs | ||
| * `cloud-token` - (Optional) The Atlas Cloud token to use for authentication. To create | ||
| a cloud token see the [docs](https://atlasgo.io/cloud/bots). | ||
| * `version` - (Optional) The version of the Atlas CLI to install. Defaults to the latest | ||
| version. | ||
|
|
||
| #### `dir` | ||
| ### `ariga/atlas-action/migrate/push` | ||
|
|
||
| Sets the directory that contains the migration scripts to analyze. | ||
| Push the current version of your migration directory to Atlas Cloud. | ||
|
|
||
| #### `dir-format` | ||
| #### Inputs | ||
|
|
||
| Sets the format of the migration directory. Options: `atlas` (default), | ||
| `golang-migrate`, `goose`, `dbmate`, `flyway`, or `liquibase`. | ||
| All inputs are optional as they may be specified in the Atlas configuration file. | ||
|
|
||
| #### `dev-url` | ||
| * `dir` - The URL of the migration directory to push. For example: `file://migrations`. | ||
| Read more about [Atlas URLs](https://atlasgo.io/concepts/url). | ||
| * `dir-name` - The name 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](https://atlasgo.io/concepts/dev-database). | ||
| * `tag` - The tag to apply to the migration directory. By default the current git commit hash is used. | ||
| * `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](https://atlasgo.io/atlas-schema/projects). | ||
| * `env` The environment to use from the Atlas configuration file. For example, `dev`. | ||
|
|
||
| The URL of the dev-database to use for analysis. | ||
| #### Outputs | ||
|
|
||
| * Read about [Atlas URL formats](https://atlasgo.io/concepts/url) | ||
| * Read about [dev-databases](https://atlasgo.io/concepts/dev-database) | ||
| * `url` - The URL of the migration directory in Atlas Cloud, containing an ERD visualization of the schema. | ||
|
|
||
| #### `latest` | ||
| ### `ariga/atlas-action/migrate/lint` | ||
|
|
||
| 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. | ||
| TODO | ||
|
|
||
| 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 | ||
| ``` | ||
| ### `ariga/atlas-action/migrate/apply` | ||
|
|
||
| Apply migrations to a database. | ||
|
|
||
| #### Inputs | ||
|
|
||
| ### `cloud-token` | ||
| All inputs are optional as they may be specified in the Atlas configuration file. | ||
|
|
||
| Connect the action to [Atlas Cloud](https://atlasgo.cloud/) to get access to more analyzers, | ||
| entity relationship diagrams (ERDs) of your schema, and full CI reports. | ||
| Generate the token from within Atlas Cloud by creating a CI Bot. Read the full tutorial | ||
| [here](https://atlasgo.io/cloud/getting-started#connecting-to-the-atlas-github-action). | ||
| * `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](https://atlasgo.io/atlas-schema/projects). | ||
| * `env` The environment to use from the Atlas configuration file. For example, `dev`. | ||
|
|
||
|  | ||
| #### Outputs | ||
|
|
||
| The full list of input options can be found in [action.yml](action.yml). | ||
| * `current` - The current version of the database. | ||
| * `target` - The target version of the database. | ||
| * `pending_count` - The number of migrations that will be applied. | ||
| * `applied_count` - The number of migrations that have been applied. | ||
|
|
||
| ### Legal | ||
| ### Legal | ||
|
|
||
| The source code for this GitHub Action is released under the Apache 2.0 | ||
| License, see [LICENSE](LICENSE). | ||
|
|
||
| This action downloads a binary version of [Atlas](https://atlasgo.io) which | ||
| is distributed under the [Ariga EULA](https://ariga.io/legal/atlas/eula). | ||
| is distributed under the [Ariga EULA](https://ariga.io/legal/atlas/eula). | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,137 @@ | ||
| # atlas-action (deprecated TypeScript action) | ||
|
|
||
| Note: This action is deprecated. Please use the latest version of the [Atlas Actions](../README.md). | ||
|
|
||
| A GitHub Action for [Atlas](https://github.com/ariga/atlas). | ||
|
|
||
| This action is used for [linting migration directories](https://atlasgo.io/versioned/lint) | ||
| 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. | ||
| * 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: | ||
| * [Atlas](https://atlasgo.io) | ||
| * [golang-migrate](https://github.com/golang-migrate/migrate) | ||
| * [goose](https://github.com/pressly/goose) | ||
| * [dbmate](https://github.com/amacneil/dbmate) | ||
| * [Flyway](https://flywaydb.org/) | ||
| * [Liquibase](https://www.liquibase.org/) | ||
|
|
||
| ### Usage | ||
|
|
||
| Add `.github/workflows/atlas-ci.yaml` to your repo with the following contents: | ||
|
|
||
| ```yaml | ||
| 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/*' | ||
| # Permissions to write comments on the pull request. | ||
| permissions: | ||
| contents: read | ||
| pull-requests: write | ||
| jobs: | ||
| lint: | ||
| services: | ||
| # Spin up a mysql:8.0.29 container to be used as the dev-database for analysis. | ||
| # If you use a different database, change the image configuration and update | ||
| # the `dev-url` configuration below. | ||
| mysql: | ||
| image: mysql:8.0.29 | ||
| 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/[email protected] | ||
| with: | ||
| fetch-depth: 0 # Mandatory unless "latest" is set below. | ||
| - uses: ariga/atlas-action@v0 | ||
| with: | ||
| dir: path/to/migrations | ||
| dir-format: atlas | ||
| dev-url: mysql://root:pass@localhost:3306/test | ||
| ``` | ||
| ### Configuration | ||
| Configure the action by passing input parameters in the `with:` block. | ||
|
|
||
| #### `config-path` | ||
|
|
||
| Sets the path to the Atlas configuration file. By default, Atlas will | ||
| look for a file named `atlas.hcl` in the current directory. | ||
|
|
||
| #### `config-env` | ||
|
|
||
| Sets the environment to use from the Atlas configuration file. | ||
|
|
||
| #### `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`, `dbmate`, `flyway`, or `liquibase`. | ||
|
|
||
| #### `dev-url` | ||
|
|
||
| The URL of the dev-database to use for analysis. | ||
|
|
||
| * Read about [Atlas URL formats](https://atlasgo.io/concepts/url) | ||
| * Read about [dev-databases](https://atlasgo.io/concepts/dev-database) | ||
|
|
||
| #### `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 | ||
| ``` | ||
|
|
||
| ### `cloud-token` | ||
|
|
||
| Connect the action to [Atlas Cloud](https://atlasgo.cloud/) to get access to more analyzers, | ||
| entity relationship diagrams (ERDs) of your schema, and full CI reports. | ||
| Generate the token from within Atlas Cloud by creating a CI Bot. Read the full tutorial | ||
| [here](https://atlasgo.io/cloud/getting-started#connecting-to-the-atlas-github-action). | ||
|
|
||
|  | ||
|
|
||
| The full list of input options can be found in [action.yml](action.yml). | ||
|
|
||
| ### Legal | ||
|
|
||
| The source code for this GitHub Action is released under the Apache 2.0 | ||
| License, see [LICENSE](LICENSE). | ||
|
|
||
| This action downloads a binary version of [Atlas](https://atlasgo.io) which | ||
| is distributed under the [Ariga EULA](https://ariga.io/legal/atlas/eula). |