Getting Started With Django and Heroku Pipelines
Aug 26, 2017
7 minutes read

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:

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 heroku_django
cd heroku_django

Before doing anything else, we’ll want to update the Procfile to ensure that heroku runs the migrations in pre-release:

# Add this to /Procfile
release: python 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://
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 migrate
python runserver

You should be able to navigate to localhost:8000 and browse the app:

App running locally

Navigating to the /db/ endpoint creates a simple entry in the application database and displays a log of page views.

db endpoint in Heroku app

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:

heroku login

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:

heroku open

Let’s check the /db/ endpoint (in this case,; 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:

Heroku db page

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:

Heroku postgres addon

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.

new pipeline

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 master branch
  • Production, which will house our production application.

pipeline dashboard

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 the pipeline.

From the dashboard, add your production app to the production phase by clicking “Add app…” and searching for your application’s name.

app in prod

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.

app in staging

Let’s deploy our code to this app:

git remote add heroku-staging
git push heroku-staging master

You should now be able to open the staging app in your browser. Navigating to the /db/ endpoint will help ensure the database is configured correctly:

staging db page

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 heroku-django-example-staging dashboard and enable automatic deploys.

automatic deployes

Let’s test it by making a trivial change and pushing to our github account. Open 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:

deployed staging

From this point on, all changes to the master branch will automatically be deployed to the staging application.

Review Apps

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.

review apps

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

Modify 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:

pull request

Now, create a pull request from github. Heroku’s github integration will notify you that a rew app is being created:

review app pending

And from your Heroku pipeline page, you’ll see that it auto-detected the pull request:

review app heroku

When ready, you can view the deployment directly from github:

view deployment

And you’ll notice that the change is made:

live deployment

Once again, navigating to the /db/ endpoint of this review app will indicate a cleanly-created Postgres database.

db endpoint from review app

Once the change has been reviewed, the pull request can be merged into master 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 from the master branch

Once this change has been reviewed and approved in the staging application, 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.

production updated

Your application is now moved to production, and the “branch -> pull request -> review -> merge -> promote” workflow can be repeated again.

Back to posts

comments powered by Disqus