Skip to main content

Getting Started with Ariga Cloud

Ariga Cloud is an online platform that allows developers to view their Atlas projects and track their Atlas GitHub Action CI runs. The cloud platform gives full visibility into your Atlas schema, by displaying an entity relation diagram (ERD) that shows the schema changes, as well as the entire database schema.

Signing Up

Login

  1. To get started with Ariga Cloud, create an account by clicking 'sign up' on the homepage.
  2. In the sign up screen, enter your work email and choose a password.
  3. Next, you will receive an email to verify your account. From your email, Ariga Cloud will open in a new tab, and you will need to sign in to access your account.
  4. Once signed in, you will be prompted to create an organization. After creating the organization, you will be able to invite team members to join. Choose a meaningful name for the organization, as it will also be your subdomain. For example, "Acme Corp" will be available at "acme-corp.ariga.cloud".
note

Currently, the system only allows users to sign up for one organization. If you wish to create multiple organizations under the same user, you can create a task-specific email address (for Google users only). Create multiple emails that all link back to your regular address by adding a plus sign and any word before the @ sign in your address.

Connecting to the Atlas GitHub action

At first you will notice that your projects and CI runs pages are empty. In order to connect the organization to your GitHub repository, you will need to setup the Atlas GitHub action on your repository by following these steps:

note

If you already have the Atlas GitHub action set up, you may skip step 4. In step 5, only add ariga-token: ${{ secrets.ARIGA_TOKEN }} to your yaml file.

  1. From the Settings page, generate an access token under 'Tokens'.
  2. On your GitHub repo, under the 'Settings' section, click on 'Secrets' > 'Actions' to create a new repository secret.
  3. Name your secret (for example, ARIGA_TOKEN) and paste the generated token from step 2.
  4. Install the Atlas GitHub Action by adding a file named .github/workflows/atlas-ci.yaml to your repo.
  5. Based on the type of database you are using, copy the following code into the workflow definition file. Set up the ariga-token input parameter to the secret name you chose in the previous step, and ensure your mainline branch and migration directory path are configured correctly:
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.0.29 container to be used as the dev-database for analysis.
mysql:
image: mysql:8.0.29
env:
MYSQL_ROOT_PASSWORD: pass
MYSQL_DATABASE: test
ports:
- "3307: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, goose, dbmate, flyway, liquibase
dev-url: mysql://root:pass@localhost:3307/test
ariga-token: ${{ secrets.ARIGA_TOKEN }}
  1. After merging the workflow to your mainline branch, the workflow will be triggered.
  2. Refresh Ariga Cloud and your project will appear!

Setup Projects

Viewing CI Runs

In the system, you can view all the CI runs that were triggered by the Atlas GitHub workflow.

Each run includes the following:

  • A summary of the run.
  • SQL statements that were analyzed.
  • An ERD that shows the changes made to the schema, as well as a full view.

A run can complete in one of three ways:

Successful Run

The CI ran successfully and no errors or issues were found in your SQL statements or Atlas sum file.

Inviting Members

Under 'Settings' > 'Members', you can invite team members to your organization. These members will receive an email with a link to Ariga Cloud, and will be required to sign up with the same email in order to access the organization.

Regenerating Tokens

It is possible to regenerate the access token, however once you do so the old token will be invalidated. When choosing to regenerate the token, you must remember to copy the new one into your GitHub project's 'Secrets'.

info

For more help, reach out to us on our Discord server.