Skip to main content

Getting Started with Atlas Cloud

Atlas 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 Atlas 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, Atlas 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 asked to confirm the service agreement in order to continue with the login process.
  5. Next, 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.atlasgo.cloud".

Choosing an organization

Choosing organization Atlas Cloud allows you to be a part of multiple organizations. After logging in (not including the first login), you will see all the organizations you have access to. Choose the organization you would to log in to. If you would like to create a new organization, click 'create a new organization'. While logged in to one organization, you would be able to switch to another by clicking on your avatar on the top right corner and choose the organization you would like to switch to.

Switching organization

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. GitHub Secrets
    note

    If you do not see this on your GitHub repository, ask your repository owner for access or help.

  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 Atlas 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 Atlas 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.