Deploy Automatically with GitHub

Install the Atlas App Services GitHub App

In order to automatically deploy based on a GitHub repository, Atlas App Services 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 App Services UI. Select the Configuration tab and then click Install App Services on GitHub. A new browser window will open to the GitHub application installation flow.

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 App Services 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, return to the Configuration tab and click the Authorize button to finish connecting App Services to GitHub. This leads you to a github permissions screen. Click Authorize MongoDB Atlas App Services.

Specify a GitHub Repository

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

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 configuration files that define your application. You can create the configuration manually or export the application directory of an existing app.

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

git add -A
git commit -m "Adds App Services 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 App 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 App by pushing them to the GitHub repo that you specified. If Automatic GitHub Deployment is enabled, App Services 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, App Services 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.

Authenticate a MongoDB Atlas User

Use your MongoDB Atlas Admin API Key to log in to the CLI:

appservices login --api-key="<my api key>" --private-api-key="<my private api key>"

Run the Deploy Configure Command

The App Services CLI can walk you through the process of configuring automatic deployment. This is an interactive command.

appservices deploy configure

The command also supports additional flags that you can optionally include. For information on these flags, refer to appservices deploy configure.

App Services CLI immediately enables automatic deployment when you complete this command. You don't need to run the enable command as an additional step.

Disable, Enable, or View Configuration Details (Optional)

You can use the App Services CLI to view configuration details after you have configured automatic deployment.

appservices deploy describe

You can also disable and enable automatic deployment using the App Services CLI. For more information about these commands and their options, refer to appservices deploy.

Authenticate a MongoDB Atlas User

Call the admin user authentication endpoint with your MongoDB Atlas API key pair:

curl -X POST \
  https://services.cloud.mongodb.com/api/admin/v3.0/auth/providers/mongodb-cloud/login \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "username": "<Public API Key>",
    "apiKey": "<Private API Key>"
  }'

If authentication succeeds, the response body contains a JSON object with an access_token value:

{
  "access_token": "<access_token>",
  "refresh_token": "<refresh_token>",
  "user_id": "<user_id>",
  "device_id": "<device_id>"
}

The access_token grants access to the App Services Admin API. You must include it as a Bearer token in the Authorization header for all Admin API requests.

Get an Existing Deployment Configuration (Optional)

You can get the existing deployment configuration for your App by making a GET request to the Get the Deployment Configuration endpoint.

curl -X GET \
   https://services.cloud.mongodb.com/api/admin/v3.0/groups/{groupId}/apps/{appId}/deploy/config \
   -H 'Authorization: Bearer <access_token>'

Update the Deployment Configuration

You can update the existing deployment configuration for your App by making a PATCH request to the Configure Deployment endpoint.

curl -X PATCH \
   https://services.cloud.mongodb.com/api/admin/v3.0/groups/{groupId}/apps/{appId}/deploy/config \
   -H 'Authorization: Bearer <access_token>' \
   -d '{
      "ui_drafts_disabled": true,
      "automatic_deployment": {
         "enabled": true,
         "provider": "github",
         "installation_ids": [
            "string"
         ]
      },
      "last_modified": 0
      }'