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, you can either sign up with GitHub or 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 in the bottom left corner and choose the organization you would like to switch to.

Switching organization

Connecting to the Atlas GitHub action

In order to connect to the Atlas GitHub Action, we will create a bot with permission to report CI run results. Bots are used to manage permissions and make sure dedicated actions, such as reporting CI results, are executed only by the entity with the desired permission. 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, under 'Bots', click on "Create Bot" to create a new CI bot.
    The CI bot will be used to connect your GitHub and will allow Atlas Cloud to lint your pull requests.
  2. After saving your CI bot, click on "Create Token", and generate a token for your bot.
  3. 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.

  4. Name your secret (for example, ARIGA_TOKEN) and paste the generated token from step 2.
  5. Install the Atlas GitHub Action by adding a file named .github/workflows/atlas-ci.yaml to your repo.
  6. 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

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.

Deleting Bots and Tokens

It is possible to delete a bot, however once you do all of its tokens will be invalidated.
If you would like to generate a new bot with a new token, make sure to update your GitHub project's 'Secrets' with the new token.

info

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