Navigation

Deploy Automatically with GitHub

Overview

You can deploy changes to your application by directly modifying the underlying configuration files in an application directory that you host on GitHub. Stitch uses Git to version control your application and can automatically deploy new versions based on the latest commit in a GitHub repository that you specify. You can clone the GitHub repository to your computer and then use standard Git commands to pull down the latest versions and push new versions. This guide assumes that you’re using the Git CLI.

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
2

Specify a GitHub Repository

Once you have linked your GitHub account to your Stitch app, you can specify a repository that Stitch should automatically deploy. Click the Repository drop-down, select the repo’s name from the list, and then click Save.

GitHub repository selection

Note

The list of repositories will only contain repos that you have granted Stitch 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 repository needs to contain an application directory with configuration files that define your application. You can create the application directory manually or export the application directory using the --for-source-control option for an existing app.

Important

Stitch applications deployed via GitHub must not specify the name, app_id, location, or deployment_model fields in the stitch.json file. Applications deployed via GitHub must also omit the config.clusterName field of the config.json of any Atlas clusters 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 Stitch Application Directory"

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

git push origin master
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 Stitch UI
5

Make Changes to Your Application

A deployment contains one or more changes that you’ve 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 File Schema 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’ve updated your application configuration, you can deploy the updates as a new version of your Stitch app by pushing them to the GitHub repo that you specified. If Automatic GitHub Deployment is enabled, Stitch immediately deploys the latest commit from the master branch.

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 master

Once you successfully push your changes to master in the GitHub repo, Stitch 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 Stitch UI.