On this page
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.
- 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
gitinstalled, 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.
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 Deployment in the left navigation menu 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 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:
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.
After you install the application, click Authorize to finish connecting Realm to GitHub. This leads you to a github permissions screen, where you will click Authorize MongoDB Realm.
You can manage permissions for the Realm GitHub application from the Installed GitHub Apps page in your GitHub settings.
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.
The list of repositories will only contain repos that you have granted Realm read access to.
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.
In order to deploy successfully, your git repository must not contain some fields that are present in your application export.
If you are using realm-cli v1.x for the v1 app
structure, use the
--for-source-control flag when you export an app.
This flag omits the
fields in the
config.json file, and the
config.clusterName field of
config.json of any Atlas data sources
connected to the application.
If you are using the realm-cli v2.x for the v2 app
--for-source-control is no longer an available flag. The
v2 app structure no longer contains most of those references. The only
field you must remove is the
app_id from the
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>
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.
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 Realm Application Configuration reference page and individual component reference pages for details on the structure and schema of your application directory.
Because breaking - also called destructive - schema changes require special handling, Realm does not support making breaking schema changes via automated deploy with GitHub. Instead, you should make breaking changes from the Realm UI.
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.
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.
Automatic GitHub deployment does not prevent you from making changes to your Realm app from the Realm UI. You can make changes to your app via the UI, and Realm automatically commits changes back to your linked GitHub repository.
If your linked GitHub repository contains new commits that are not reflected in your MongoDB Realm UI changes, Realm 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
bot appears as the commit author.
With automatic GitHub deployment enabled, avoid making changes to your app with Realm CLI because:
- If you push changes with the CLI while GitHub deployment is enabled, Realm 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 Realm 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 Realm app by modifying a repo hosted on GitHub.
- While 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.
- When you make changes via the Realm UI after enabling Automatic GitHub Deployment, those changes are automatically committed back to your linked repository.
- Do not use Realm CLI to update configuration files after enabling Automatic GitHub Deployment.