Navigation

Deploy Automatically with GitHub

Overview

You can configure a Realm app to automatically deploy whenever you push updated 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 contain an application directory or be empty. 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.

Procedure

1

Install the MongoDB Realm GitHub App

In order to automatically deploy based on a GitHub repository, Realm requires that you install a GitHub app that has, at minimum, read access to the repository.

To install the app, click Deploy in the left-hand navigation of the Realm UI. Select the Configuration tab and then click Install Realm on GitHub. A new browser window will open to the GitHub application installation flow.

GitHub Authentication

GitHub may require you to provide your GitHub account credentials before you can install the app.

Select the GitHub account or organization for which you want to install the app:

GitHub Application install location screen

Specify one or more repositories for which you want to grant MongoDB Realm 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 Application permissions request screen

After you install the application, click Authorize to finish connecting Realm to GitHub.

GitHub Permissions

You can manage permissions for the Realm GitHub application from the Installed GitHub Apps page in your GitHub settings.

2

Specify a GitHub Repository

Once you have linked your GitHub account to your Realm app, you can specify a repository that Realm should automatically deploy. Specify the Repository, Branch, and Directory that contain the Realm app’s configuration files and then click Save.

GitHub repository selection

Note

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

3

Initialize the Repository

Clone a local copy of the Git repository that you specified:

git clone https://github.com/<organization>/<repo>.git

The configured branch and directory must contain an application directory with configuration files that define your application. You can create the application directory manually or export the application directory of an existing app (using the --for-source-control option).

Export For Source Control

Realm apps deployed via GitHub must not specify the name, app_id, location, or deployment_model fields in the config.json file. Applications deployed via GitHub must also omit the config.clusterName field of the config.json of any Atlas data sources connected to the application.

Application configurations exported with the --for-source-control flag omit these fields automatically.

Add the application directory to the repository and then commit the changes:

git add -A
git commit -m "Adds Realm Application Directory"

Once you have committed the latest version of the application to the repository, push it to your GitHub repository:

git push origin <branch name>
4

Enable Automatic Deployment

After you have specified a repository to deploy and initialized it with the latest version of your app, you need to enable automatic deployment to begin deploying it. 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.

Enable Automatic GitHub Deployment in the Realm UI
5

Make Changes to Your Application

A deployment contains one or more changes that you have made to your application since the previous deployment. Make any additions, modifications, or deletions to the repository that you want to include in your deployment.

Refer to the Application Configuration Files reference page and individual component reference pages for details on the structure and schema of your application directory.

6

Commit and Push Your Changes

Once you have updated your application configuration, you can deploy the updates as a new version of your Realm app by pushing them to the GitHub repo that you specified. If Automatic GitHub Deployment is enabled, Realm immediately deploys the latest commit for the configured branch and directory.

When you are ready to deploy, commit all of the files that you want to include and then push them to GitHub:

git add -A
git commit -m "<commit message>"
git push origin <branch name>

Once you successfully push your changes to GitHub, Realm immediately deploys a new version of your application that matches the state of the latest commit. Client applications will automatically use the newest version, so make sure that you also update your client code to use the new version if necessary.

Deployment History

You can see the currently deployed version of your application as well as a historical log of previous deployments in the Deployment History table in the Realm UI.

Summary

  • You can deploy your Realm app by modifying a repo hosted on GitHub.
  • When Automatic GitHub Deployment is enabled, MongoDB Realm immediately deploys the latest commit. To deploy, commit your changes locally, then push them to your repo on GitHub.
  • MongoDB Realm keeps track of your Deployment History.