In a , we explored how to automate deployments to Heroku using GitLab CI/CD. That setup deployed the app to its production environment every time we pushed code to the branch. previous article main In this article, we’ll consider a slightly more nuanced approach: What if we have multiple environments? Most engineering organizations use at least three environments: a local development environment, a staging environment, and a production environment. Additionally, some engineering teams follow a , where they have a branch and a branch. This strategy has since fallen out of favor and been replaced by , but it’s not uncommon to find organizations still following this practice. Gitflow branching strategy dev main trunk-based development Today, we will look at how to configure GitLab CI/CD to deploy our app to our staging environment when we push to the branch and deploy our app to our production environment when we push it to the branch. dev main Getting Started Before we begin, we’ll need two things: a Heroku account and a GitLab account. Heroku is a great place to host and deploy your apps. As a platform as a service (PaaS), Heroku allows you to focus on building cool things while abstracting away much of the infrastructure complexity. You can . create a Heroku account here GitLab is a great place to store your code. Beyond just being a source code management tool, GitLab also offers native CI/CD capabilities so you can set up pipelines to test and deploy your code without requiring another third-party tool. You can . create a GitLab account here The demo app shown in this article uses both GitLab and Heroku. You can . find all the code in the GitLab repo here Running Our App Locally You can run the app locally by cloning the repo, installing dependencies, and running the start command. In your terminal, do the following: $ git clone https://gitlab.com/tylerhawkins1/heroku-gitflow-staging-production-gitlab-cicd-demo.git
$ cd heroku-gitflow-staging-production-gitlab-cicd-demo
$ npm install
$ npm start After starting the app, visit in your browser, and you’ll see the app running locally: http://localhost:5001/ Deploying Our App to Heroku Now that the app is running locally let’s deploy it to Heroku so that you can access it anywhere, not just on your machine. Remember that we are going to deploy your app to both a staging environment and a production environment. That means that we’ll have two Heroku apps based on the same GitLab repo. If you don’t already have the installed on your machine, you’ll need to install it before moving on. Heroku CLI After installing the Heroku CLI, run the following commands from your terminal to check out the branch, create a new production Heroku app, deploy it to your production environment, and open it in your browser: main $ git checkout main
$ heroku create heroku-gitlab-ci-cd-production --remote heroku-production
$ git push heroku-production main
$ heroku open --remote heroku-production With that, you should see the same app, but this time running on a Heroku URL instead of on localhost. Nice work — you’ve deployed your Heroku app to production! But we’re not done yet. We also need to configure and deploy your staging app. To do this, run this similar set of commands shown below: $ git checkout dev
$ heroku create heroku-gitlab-ci-cd-staging --remote heroku-staging
$ git push heroku-staging main
$ heroku open --remote heroku-staging Now, you’ll have the same app deployed again, but this time to a different URL that will serve as your staging environment. Now we have both of your environments configured! Note the differences and similarities between the commands for the production app and the staging app: The production app uses the branch and the staging app uses the branch. main dev The production app is called , and the staging app is called . heroku-gitlab-ci-cd-production heroku-gitlab-ci-cd-staging The production app’s git remote is called , and the staging app’s git remote is called . heroku-production heroku-staging Both the production app and the staging app’s git remotes use a branch since . main Heroku only deploys the app when code is pushed to its main branch Keep in mind that branch is different from set of and branches. The branch that you’re pushing to here is the branch on your git remote — in this case, Heroku. this main your main dev main main So when you’re on your local branch and run , you’re pushing your branch to the Heroku production app’s branch. And when you’re on your local branch and run , you’re pushing your branch to the Heroku staging app’s branch. main git push heroku-production main main main dev git push heroku-staging main dev main Making Changes to Our App Now that we have our Heroku app up and running, what if we want to make some changes? Following a rough approximation of the Gitflow branching strategy, we could do the following: Check out the branch dev Make changes to the code Add, commit, and push those changes to the branch dev Deploy those changes to the staging Heroku app by running git push heroku-staging main Check out the branch main Merge the branch into the branch dev main Deploy those changes to the production Heroku app by running git push heroku-production main (If we were truly following Gitflow, we’d have created a feature branch to merge into , and a release branch to merge into , but we’ve omitted those steps to keep things simple.) dev main Now, wouldn’t it be nice if we could automate the deployment to either of our environments instead of having to deploy them manually all the time? This is where GitLab CI/CD comes into play. Continuous Integration / Continuous Deployment Continuous integration (CI) is all about committing often and keeping the build in a good state at all times. Typically you would verify that the build is in a good state by running checks in a CI pipeline. These checks might include linters, unit tests, and/or end-to-end tests. Continuous deployment (CD) is all about deploying frequently. If the checks in the CI pipeline pass, then the build gets deployed. If the checks in the CI pipeline fail, then the build does not get deployed. With GitLab CI/CD, we can configure our CI pipeline to do exactly this — run our tests and then deploy our app to Heroku if the tests all pass. Most importantly, for our setup, we can configure rules within our CI pipeline to specify where the app should be deployed. Configuring GitLab CI/CD We can create a CI pipeline in GitLab programmatically using a file. Our file looks like this: .gitlab-ci.yml image: node:20.10.0

cache:
  paths:
    - node_modules/

before_script:
  - node -v
  - npm install

stages:
  - test
  - deploy

unit-test-job:
  stage: test
  script:
    - npm test

deploy-job:
  stage: deploy
  variables:
    HEROKU_APP_NAME: $HEROKU_APP_NAME_PRODUCTION
  rules:
    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH
      variables:
        HEROKU_APP_NAME: $HEROKU_APP_NAME_PRODUCTION
    - if: $CI_COMMIT_REF_NAME =~ /dev/
      variables:
        HEROKU_APP_NAME: $HEROKU_APP_NAME_STAGING
  script:
    - apt-get update -yq
    - apt-get install -y ruby-dev
    - gem install dpl
    - dpl --provider=heroku --app=$HEROKU_APP_NAME --api-key=$HEROKU_API_KEY GitLab CI pipelines consist of stages and jobs. Each stage can contain one or more jobs. In our pipeline, we have two stages: and . In the stage, we run our unit tests in the . In the stage, we deploy our app to Heroku in the . test deploy test unit-test-job deploy deploy-job We can only progress to the next stage if all the jobs in the previous stage pass. That means if the unit tests fail, then the app won’t be deployed, which is a good thing! We wouldn’t want to deploy our app if it was in a bad state. You’ll note that the stage has a section with some conditional logic in place. This is where we specify to which environment our app should be deployed. If we’re on the branch, then we deploy our production app. If we’re on the branch, then we deploy our staging app. deploy rules main dev You’ll also note that the stage references several variables called , , and . These are stored as . deploy $HEROKU_APP_NAME_PRODUCTION $HEROKU_APP_NAME_STAGING $HEROKU_API_KEY CI/CD variables within GitLab If you’re setting this up in your own GitLab account, you’ll need to first find your API key in your Heroku account. Within your Heroku account settings, you should see a section for your API key. If you haven’t generated an API key yet, generate one now. Next, in your GitLab project, click on > > . Expand that section and add three new variables: Settings CI/CD Variables The value for will be the API key from your Heroku account. $HEROKU_API_KEY The value for will be the name of your production Heroku app. My production app’s name is , but since Heroku app names are universally unique, yours will be something different. $HEROKU_APP_NAME_PRODUCTION heroku-gitlab-ci-cd-production The value for will be the name of your staging Heroku app. My staging app’s name is . Again, since Heroku app names are universally unique, yours will be something different. $HEROKU_APP_NAME_STAGING heroku-gitlab-ci-cd-staging With that, your GitLab CI pipeline is ready to go! Let’s test it out. Deploying Our Heroku App to the Staging Environment Let’s check out the branch and make a change to the code in our app. I made a simple change to the heading text and added several new lines to the text in the UI. You can make a similar change in your code. dev Now, add, commit, and push that change to the branch. This will start the GitLab CI pipeline. You can view the pipeline within GitLab and see the progress in real-time. dev If everything goes well, you should see that both the and stages have passed. Now, go check out your hosted Heroku app at the staging environment URL. The GitLab CI pipeline took care of deploying the app for you, so you’ll now see your changes live in the staging environment! test deploy With a staging environment set up, you now have a great place to manually test your code in a hosted environment. This is also a perfect spot for QA testers or product managers to verify changes before they go to production. Now, check out your production app URL. You’ll note that it’s still showing the old UI without the most recent changes. This is because the GitLab CI pipeline only deployed the changes to the staging environment, not the production environment. We’ve verified that the code looks good in our staging environment, so let’s promote it to our production environment. Deploying Our Heroku App to the Production Environment Let’s check out the branch and then merge the branch into your branch. You could do this through a pull request or by running and then . main dev main git merge dev git push This will start the GitLab CI pipeline once again, but this time, it will be preparing to deploy your production app. You can also view all the pipeline runs on the Pipelines page in GitLab to see the various builds for your and branches: dev main Once the pipeline finishes, visit the URL for your production Heroku app. You should now see your changes also deployed in production. Great work! Conclusion A good CI pipeline allows you to ship new features quickly and confidently without manually managing the deployment process. Having multiple environments configured for local development, staging, and production gives you more control over where and when code is released. Heroku and GitLab CI/CD allow you to automate all of this to make your DevOps processes a breeze! Also published . here

Walkthroughs, tutorials, guides, and tips. This story will teach you how to do something new or how to do something better.

Too Long; Didn't Read

In your car, at home, or at work — Bosch technology shapes many areas of life.

Configuring GitLab CI/CD for Multi-Environment Deployments to Heroku

Too Long; Didn't Read

Tyler Hawkins

STORY’S CREDIBILITY

Guide

Share Your Thoughts

About Author

TOPICS

THIS ARTICLE WAS FEATURED IN...

Configuring GitLab CI/CD for Multi-Environment Deployments to Heroku

Too Long; Didn't Read

Tyler Hawkins

STORY’S CREDIBILITY

Guide

Share Your Thoughts

About Author

TOPICS

THIS ARTICLE WAS FEATURED IN...

RELATED STORIES