Docs Menu

Docs HomeAtlas App Services

Deploy Automatically with GitHub

On this page

  • Overview
  • Prerequisites
  • Enable Automatic Deployment with GitHub
  • Make Changes from the UI
  • Make Changes from the CLI
  • Summary

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.

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

You can enable automatic deployment with GitHub using the App Services UI, the App Services CLI, or the App Services Admin API.

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.

GitHub repository selection

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

GitHub repository selection

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.

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

←  Configure an App EnvironmentSet Up a CI/CD Pipeline →