Heroku pipelines with the github integration make it easy to setup a continuous integration workflow for Django apps. We’ll review Heroku Pipelines by way of example:
- Copying Heroku’s “getting started” django application and testing it locally
- Doing an initial deploy to a Heroku production application
- Setting up a Heroku pipeline
- Integrating with github to automatically launch review apps
- Promoting staging application to production
Cloning the Heroku “Getting Started” App
You’ll need the following requirements to get started:
- The heroku cli
- A free heroku account
- A github account
For this tutorial, we’ll use heroku’s python-getting-started application on github, which is already configured with Heroku’s best practices. For your own project, it’s easiest to use Heroku’s Django template when creating a project .
Since we’ll be using Heroku’s github integration, we’ll create a clean repository of our own so we can commit changes and experiment with pull requests. We could fork the repository instead, but bootstrapping a clean repository ensures we don’t accidentally make pull requests to Heroku’s repo.
git clone -o boilerplate https://github.com/heroku/python-getting-started.git heroku_django cd heroku_django
Before doing anything else, we’ll want to update the
Procfile to ensure that
heroku runs the migrations in
# Add this to /Procfile release: python manage.py migrate
Be sure to commit the change:
git add Procfile git commit -m "Include migration in pre-release"
Now we’ll create a clean github project called
heroku_django and set this as
the remote origin (be sure to replace
danpelota with your own github account
when running the code below):
git remote add origin ssh://email@example.com/danpelota/heroku_django git push origin master
Now we have a clean repository, separate and distinct from the original heroku repo.
Running the App Locally
Let’s get the application off the ground. Create a new virtual environment and install the requirements.
python3 -m venv venv source venv/bin/activate pip install -r requirements.txt
Ensure we can launch the app locally:
python manage.py migrate python manage.py runserver
You should be able to navigate to localhost:8000 and browse the app:
Navigating to the
/db/ endpoint creates a simple entry in the application
database and displays a log of page views.
This will come in handy later when validating the database configuration is working as expected.
Launching on Heroku
Now that we’ve confirmed we can run the application locally, let’s launch a Heroku instance with this code.
Login to heroku from the command line and enter your credentials:
Now you can create an app and deploy it. (We’ll name this application with the
-prod suffix because we’ll be moving this to the production phase of the
pipeline., If you’re trying this code, you may need to use a different name to
avoid conflicts with other Heroku apps.)
heroku create heroku-django-example-prod git push heroku master
This will create a Heroku app called
heroku-django-example-prod and push your
code to it. The site should be accessible at the Heroku URL, or by running:
Let’s check the
/db/ endpoint (in this case,
https://heroku-django-example-prod.herokuapp.com/db/; be sure to change
the URL if your app is named differently. You should be able to refresh the
page a few times and see the database entries reflected in the view:
But wait…we never setup a database! If you navigate to your app in the Heroku dashboard, you’ll see that Heroku has helpfully configured the Heroku Postgres addon for us:
The fact that the
/db/ endpoint is functioning correctly indicates that (1)
this addon has been correctly configured, and (2) our migrations are indeed
running as instructed in the Procfile above.
Setting Up a Pipeline
Now that we know we can deploy the app to Heroku, let’s setup a pipeline. From the Heroku console, click “new -> pipeline” (you can also do this via command line). You’ll be asked to create a new pipeline, which we’ll name “heroku-django-pipe”
We’ll also connect the pipeline to the github repository to enable review apps. Click “Connect to GitHub” and authenticate to your github account to enable this.
Click “Create Pipeline” to initialize this pipeline.
You should see your new pipeline in the Heroku dashboard, with three stages:
Review Apps, which will be created automatically with github pull requests
Staging, which we’ll configure to auto-deploy from the current state of our
Production, which will house our production application.
Adding Our Application to the Pipeline
We’ll need to add an application to our newly-created pipeline. To start, we’ll
add our production app (
heroku-django-example-prod) to the production stage of
From the dashboard, add your production app to the
production phase by clicking
“Add app…” and searching for your application’s name.
Next, we’ll create a new app to hold our “staging” code and add it to the pipeline. From the command line:
heroku create heroku-django-example-staging
We can now add this app to the staging step of the pipeline from the interface.
Let’s deploy our code to this app:
git remote add heroku-staging https://git.heroku.com/heroku-django-example-staging.git git push heroku-staging master
You should now be able to open the staging app in your browser. Navigating to
/db/ endpoint will help ensure the database is configured correctly:
Note that the previous database entries from the production app are not reflected. Heroku has automatically configured this staging application with it’s own database via the Heroku Postgres addon.
Configuring Auto Deployments
Let’s configure the staging application to automatically deploy from the github
master branch. Go to the Deploy tab of the
dashboard and enable automatic deploys.
Let’s test it by making a trivial change and pushing to our github account.
hello/templates/index.html and change this line:
<p>This is a sample Python application deployed to Heroku. It's a reasonably simple app - but a good foundation for understanding how to get the most out of the Heroku platform.</p>
To something like this:
<p>We've made a change!</p>
Then, commit the change and push it to your github account:
git add . git commit -m "Change to welcome text" git push origin master
You’ll notice that the staging app in the Heroku pipeline was automatically deployed. Browsing the app should reflect the change:
From this point on, all changes to the
master branch will automatically be
deployed to the staging application.
Let’s extend our workflow to include the automatic creation of review apps.” From the pipeline interface, click “enable review apps.” Be sure to enable creating review apps from pull requests automatically.
Let’s make another change to our code base to test the review apps. First, create a new branch for our change.
git branch feature-welcome-text git checkout feature-welcome-text
hello/templates/index.html one more time, and change this:
<p>We've made a change!</p>
To something like this:
<p>Review this change!</p>
Add and commit to the new branch
git add . git commit -m "Change for review" git push --set-upstream origin feature-welcome-text
GitHub will notify you of the change and prompt to do a pull request:
Now, create a pull request from github. Heroku’s github integration will notify you that a rew app is being created:
And from your Heroku pipeline page, you’ll see that it auto-detected the pull request:
When ready, you can view the deployment directly from github:
And you’ll notice that the change is made:
Once again, navigating to the
/db/ endpoint of this review app will
indicate a cleanly-created Postgres database.
Once the change has been reviewed, the pull request can be merged into
from github. When this happens, Heroku does a few things:
- The review app is automatically removed
- The staging application is updated since it is configured to auto-deploy
Once this change has been reviewed and approved in the
the change can be promoted to production from the pipeline dashboard:
Note that the Heroku application wasn’t moved when promoting to production.
Instead, only the codebase (or more accurately, the compiled
slug) is moved. You can
see for yourself by looking once again at the
/db/ endpoint of the
application in the production phase. Note that while the changes to the home
page are now reflected in production, the
production has still maintained
it’s own database with the previous page view entries.
Your application is now moved to production, and the “branch -> pull request -> review -> merge -> promote” workflow can be repeated again.