Deploying to Heroku with GitLab CI/CD

Frequent commits and deployments are now a staple of modern development practices, thanks to Continuous Integration (CI) and Continuous Deployment (CD). Gone are the days of lengthy release cycles. With platforms like GitLab and Heroku, you can automate deployments directly from your repository, ensuring your application is live every time changes are pushed to your main branch. This guide will walk you through deploying a Heroku app using GitLab CI/CD pipelines.

Why Use GitLab CI/CD for Heroku?

GitLab’s built-in CI/CD capabilities and Heroku’s Platform as a Service (PaaS) offering make deployment easy by:

• Automating testing, building, and deploying directly from GitLab
• Reducing manual steps and human error
• Enabling continuous delivery directly to Heroku, ideal for both small and large-scale applications

Prerequisites

To follow along, you’ll need:

1. A GitLab account to host your code and manage pipelines.
2. A Heroku account for app deployment and hosting.

Let’s jump in!

Step 1: Setting Up Your Heroku App

1. Create a New Heroku App: Log in to Heroku and navigate to your dashboard. Click New > Create New App.
2. Configure App Details: Provide a unique app name and choose your region, then click Create App.

After setting up the app, note down its name as you’ll need it in later steps.

Step 2: Prepare Your GitLab Repository

1. Create or Use an Existing GitLab Repository: Either initialize a new project on GitLab or use an existing one. Ensure your codebase is ready and includes the essential Heroku files (e.g., Procfile for specifying the web server command).
2. Add a .gitlab-ci.yml file: In the root of your repository, create a .gitlab-ci.yml file, which will contain your pipeline configuration.

Step 3: Set Up Heroku API Key in GitLab

To authenticate GitLab CI/CD with Heroku, you’ll need to securely store your Heroku API Key in GitLab’s CI/CD environment variables.

1. Get Your Heroku API Key:

   • Go to Account Settings on Heroku.
   • Scroll down to API Key and click Reveal to copy it.

2. Add the API Key in GitLab:

   • In GitLab, navigate to your project.
   • Go to Settings > CI/CD > Variables.
   • Click Add Variable and enter:
     • Key: HEROKU_API_KEY
     • Value: Paste your Heroku API key.
     • Mask: Enable masking to hide the key in logs for security.

Step 4: Define the GitLab CI/CD Pipeline

The .gitlab-ci.yml file defines the stages and steps GitLab will execute every time you push to the main branch. Here’s a basic configuration for deploying to Heroku:

# .gitlab-ci.yml

image: node:16

stages:
  - deploy

deploy_to_heroku:
  stage: deploy
  script:
    # Install Heroku CLI
    - curl https://cli-assets.heroku.com/install.sh | sh
    # Log into Heroku using the API key
    - echo "$HEROKU_API_KEY" | heroku auth:token
    # Push code to Heroku's Git
    - git remote add heroku https://heroku:$HEROKU_API_KEY@git.heroku.com/<your-heroku-app>.git
    - git push heroku main
  only:
    - main

Explanation of the .gitlab-ci.yml Configuration

• image: Specifies the Docker image to use. Here, node:16 is used for Node.js-based applications.
• stages: Defines the pipeline stages. In this case, deploy is the only stage.
• deploy_to_heroku: This job will:
  1. Install the Heroku CLI to interact with Heroku directly from the pipeline.
  2. Authenticate using the HEROKU_API_KEY.
  3. Push your code to the Heroku repository.

Note: Replace <your-heroku-app> with the name of your Heroku app.

Step 5: Run the Deployment

With everything set up, pushing code to the main branch should automatically trigger a GitLab pipeline, deploying your app to Heroku.

You can verify this by:

1. Checking the Pipeline Logs: In your GitLab project, go to CI/CD > Pipelines to see the status of the latest deployment job.
2. Visiting Your App: Open your browser and go to https://<your-heroku-app>.herokuapp.com to confirm the app is live.

Troubleshooting Common Issues

If your deployment doesn’t go as planned, here are a few things to check:

• Check the GitLab CI/CD Logs: Logs provide insights if any part of the deployment failed.
• Confirm Environment Variables: Ensure the HEROKU_API_KEY variable in GitLab is correct and not exposed.
• Run Heroku Logs: Use heroku logs --tail --app <your-heroku-app> from your local Heroku CLI to see logs if the app isn’t running as expected on Heroku.

Conclusion

Deploying a React app to Heroku with GitLab CI/CD simplifies the release process and accelerates continuous delivery. By automating the entire pipeline, you can focus on development, knowing that each push to main will take your app live.

To recap, here’s what we accomplished:

1. Created and configured a Heroku app.
2. Set up GitLab for our project with an environment variable for secure API authentication.
3. Wrote a .gitlab-ci.yml pipeline file to automate the deployment process.
4. Verified our deployment on Heroku.

By following these steps, you can take full advantage of GitLab CI/CD with Heroku for streamlined and frequent deployments.

That's all for today.

And also, share your favourite web dev resources to help the beginners here!

Connect with me:@ LinkedIn and checkout my Portfolio.

Explore my YouTube Channel! If you find it useful.

Please give my GitHub Projects a star ⭐️

Thanks for 32084! 🤗