- Stitch >
- Application Deployment >
- Deploy App Changes
Deploy Automatically with GitHub¶
On this page
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¶
Link Your GitHub Account¶
In order to automatically deploy based on a GitHub repository, Stitch requires that you link a GitHub account that has, at minimum, read access to the repository.
To link a GitHub account, click Deploy in the left-hand navigation of the Stitch UI and then select the Configuration tab. Expand the Automatic Deployment section and then click Grant GitHub Account Access. A new browser window will open to the GitHub application installation flow.
In the new window, provide your GitHub account credentials to log in.
After logging in, GitHub will prompt you to specify one or more repositories for which you want to grant Stitch 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, the window will close and the Stitch UI will update to show your linked account in the Configuration tab of the Deploy page. You can manage permissions for the Stitch 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 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.
Note
The list of repositories will only contain repos that you have granted Stitch read access to.
Initialize the Repository¶
Clone a local copy of the Git repository that you specified:
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:
Once you have committed the latest version of the application to the
repository, push it to the master
branch of your repository on
GitHub:
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’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.
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:
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.