Deploy Automatically with GitHub

You can automatically deploy changes to an Atlas Trigger whenever you push a configuration file to a GitHub repository.

You follow your standard Git workflow to make changes, which typically involves cloning the GitHub repository to your computer and using standard Git commands to make changes and push them to the repo. Atlas watches for the changes and updates your triggers automatically.

Prerequisites

A GitHub account and repository. The repository should either be empty or contain an already-exported configuration directory. For information on how to create an empty repository, see GitHub's create a repo guide.
An installed copy of the Git CLI. If you do not have git installed, see the official guide for Installing Git.
A MongoDB Atlas Programmatic API Key to authenticate and authorize access to your app's underlying Git repo. If you have not yet generated a programmatic API key for your Atlas organization, do so now.

Enable Automatic Deployment with GitHub

To enable automatic deployment with GitHub using the Atlas UI, follow these steps:

Create a new database, scheduled, or authentication trigger.
After you create the trigger, return to the Triggers page. You will see your new trigger in the list of triggers. Click the View All Apps button in the upper right corner of the page.
You are redirected to a page that lists one or more Applications. Select the one labeled Triggers.

You are now in the Triggers management page. Continue with the following steps, depending on your preferred tool:

Install the Atlas GitHub App

In order to automatically deploy based on a GitHub repository, Atlas requires that you install a GitHub app that has, at minimum, read access to the repository. To install the app, follow these steps:

Click Deployment in the left navigation menu of the Atlas UI, and then select the Configuration tab.
In Step 1, click Install App Services on GitHub. A new browser window will open to the GitHub application installation flow.
Select the GitHub account or organization for which you want to install the app.
Specify one or more repositories for which you want to grant Atlas read access. You can either select specific repositories or grant access to all of your repositories on GitHub. Select the repositories you want to use and then click Install.
GitHub may require you to provide your GitHub account credentials before you can install the app.
After you install the application, you can close the GitHub browser page and return to the Configuration page. Under Step 2, Click the Authorize button to finish connecting Atlas to GitHub.

Specify a GitHub Repository

Once you have linked your GitHub account, you can specify a repository that Atlas should automatically deploy. Under Step 2, specify the Repository, Branch, and Directory that contain the configuration files, and then click Save.

Note

The list of repositories will only contain repos that you have granted Atlas read access to.

Enable Automatic Deployment

After you have specified a repository to deploy and initialized it with the latest version of your changes, you need to enable automatic deployment. On the Configuration tab of the Deploy page, click Enable Automatic Deployment. In the modal that appears, click Enable Automatic Deployment to confirm your selection.

You can use the Atlas App Services CLI to configure, enable, or disable automatic deployment. You need to authenticate with the CLI. Once configured, you can make changes from the CLI and have those changes reflected in App and view them in the UI.

Authenticate a MongoDB Atlas User

npm install -g atlas-app-services-cli
appservices login

Run the Deploy Configure Command

The CLI can walk you through the process of configuring automatic deployment. This is an interactive command.

appservices deploy configure

The command also supports additional flags that you can optionally include. For information on these flags, refer to appservices deploy configure.

The CLI enables automatic deployment when you complete this command. You don't need to run the enable command as an additional step. You will then see the steps needed to complete this process:

appservices pull --remote=<app-id>
mv Triggers/* . && rm -r Triggers
git add .
git commit
git push origin master

Disable, Enable, or View Configuration Details (Optional)

You can use the CLI to view configuration details after you have configured automatic deployment.

appservices deploy describe

You can also disable and enable automatic deployment using the CLI. For more information about these commands and their options, refer to appservices deploy.

Make Changes from the UI

You can now make changes to your triggers via the UI, and Atlas automatically commits changes back to your linked GitHub repository. For example, you might switch to the Functions section and modify the existing function.

After making the changes in the UI, click Save Draft (if you have drafts enabled), and then Review Draft and Deploy. Click Deploy and Push to GitHub. Your GitHub repo is updated with the latest code changes.

Tip

If your linked GitHub repository contains new commits that are not reflected in your Atlas UI changes, Atlas can't automatically commit those changes to your repo. However, you can use the Export button to download the updated configuration files to your local machine, and then you push them manually to your GitHub repository.

When changes are committed to your linked GitHub repository, you'll see a Commit: <commit-hash> link in your Deployment History.

You can click that link to view the commit in GitHub. The mongodb-atlas-app-services bot appears as the commit author.

Make Changes from the CLI

You can use the CLI to make changes to your triggers. A push from the CLI automatically generates a corresponding commit in GitHub. This keeps your code changes synchronized with your version-controlled GitHub source of truth.

After making changes, run the following command:

appservices push

The CLI will show you the changes and ask you to confirm them before pushing them. The GitHub repo will also be updated.

Summary

You can deploy your triggers by modifying a repo hosted on GitHub.
While Automatic GitHub Deployment is enabled, Atlas immediately deploys the latest commit. To deploy, commit your changes locally, then push them to your repo on GitHub.
When you make changes via the Atlas UI after enabling Automatic GitHub Deployment, those changes are automatically committed back to your linked repository.
If you would like to use CLI to update configuration files after enabling Automatic GitHub Deployment, use CLI v1.1.0 or later.

Back

Triggers Limitations

Query Federated Data