Deploy Automatically with GitHub¶
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.
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 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.
You can manage permissions for the Realm GitHub application from the Installed GitHub Apps page in your GitHub settings.
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.
The list of repositories will only contain repos that you have granted Realm read access to.
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
Realm apps deployed via GitHub must not specify the
deployment_model fields in the
Applications deployed via GitHub must also omit the
field of the
config.json of any Atlas data sources connected to the application.
Application configurations exported with the
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>
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.
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 Realm Application Configuration reference page and individual component reference pages for details on the structure and schema of your application directory.
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.
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.
- 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.