Docs Home → Atlas App Services
Deploy Automatically with GitHub
On this page
Overview
You can configure an Atlas App Services App to automatically deploy whenever you push App configuration files to a GitHub repository. You can clone the GitHub repository to your computer and then use standard Git commands to pull down the latest versions and deploy new changes.
Prerequisites
A GitHub account and repository. The repository should either be empty or contain an exported configuration directory for an existing App. 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
You can enable automatic deployment with GitHub using the App Services UI, the App Services CLI, or the App Services Admin API.
Make Changes from the UI
Automatic GitHub deployment does not prevent you from making changes to your App from the App Services UI. You can make changes to your app via the UI, and App Services automatically commits changes back to your linked GitHub repository.
Tip
If your linked GitHub repository contains new commits that are not reflected in your App Services UI changes, App Services 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 app's Deployment History.
You can click that link to view the commit in GitHub. The mongodb-realm
bot appears as the commit author.
Make Changes from the CLI
Previously, we have recommended that you avoid making changes to your app with App Services CLI after configuring automatic deployment. Starting with App Services CLI v1.1.0 and later, you can safely use the App Services CLI to make changes to your app.
App Services CLI version 1.1.0 and later
In App Services CLI v1.1.0 and later, a push from the App Services CLI automatically generates a corresponding commit in GitHub. This keeps your code changes synchronized with your version-controlled GitHub source of truth.
App Services CLI version 1.0.3 and earlier
In App Services CLI v1.0.3 and earlier, avoid making changes to your app with the App Services CLI after configuring automatic deployment, because:
If you push changes with the CLI while GitHub deployment is enabled, App Services deploys the changes but does not commit them back to your linked repository.
The configuration files in your repository no longer reflect the current state of your app.
To get the changes you pushed, a contributor must manually pull the latest configuration files directly from your App. The GitHub repository is no longer the source of truth.
If a contributor adds a new commit to a stale repo, they overwrite any deployed but uncommitted changes.
Summary
You can deploy your App by modifying a repo hosted on GitHub.
While Automatic GitHub Deployment is enabled, App Services 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 App Services UI after enabling Automatic GitHub Deployment, those changes are automatically committed back to your linked repository.
If you would like to use App Services CLI to update configuration files after enabling Automatic GitHub Deployment, use App Services CLI v1.1.0 or later.