Skip to main content

Monitor your database schema with GitHub Actions

Connectivity requirements

In order to function, Atlas must be able to establish a connection to your database. This means you need to ensure that your database is accessible from the GitHub Actions runners.

To learn about different approaches to establish network access, see the Connect to your database from GitHub Actions guide.

The following guide will quickly walk you through how to get started with Atlas Schema Monitoring in under 5 minutes using the ariga/atlas-action/monitor/schema Action.

1. Create bot token in Atlas Cloud​

Head over to your Atlas Cloud account and click on the top level Monitoring navigation entry. Choose the GitHub Action card, click on the Generate Token button. Copy the token.

Follow to your GitHub repository and go to Settings -> Secrets and add a new secret called ATLAS_CLOUD_TOKEN with the value of the token you just copied.

2. Create a new GitHub Actions Workflow for schema monitoring​

Save the workflow file below as .github/workflows/monitor-schema.yaml in your repository.

Make sure that DB_URL is stored as a repository secret with the value of your database url or replace ${{ secrets.DB_URL }} with your database url.

Replace the slug with the name you want to give to your database. The slug is used to uniquely identify the database in Atlas Cloud, even when the database URL changes.

name: Atlas Schema Monitoring
on:
  workflow_dispatch:
  schedule:
    - cron: '0 */4 * * *'  # every 4 hours
jobs:
  monitor:
    runs-on: ubuntu-latest
    steps:
      - uses: ariga/setup-atlas@v0
      - uses: ariga/atlas-action/monitor/schema@v1
        with:
          cloud-token: ${{ secrets.ATLAS_CLOUD_TOKEN }}
          url: ${{ secrets.DB_URL }}
          slug: my-database

Then commit and push the changes to your repository.

3. Run the GitHub Action​

Once committed, go to the Actions tab in your repository, choose the Atlas Schema Monitoring workflow, and click on Run workflow.

After the workflow finishes, it should show you a link to the Atlas Cloud where you can view the schema of your database.

4. View the schema in the Atlas UI​

Click on the link provided in the logs to view the schema in the Atlas UI.

Next steps​