Setting up a GitLab integration with Heroku

An integration between Productboard and GitLab helps bridge the gap between your product discovery and product delivery processes by helping product managers and developers collaborate more efficiently. This article will walk you through how to set up your own Productboard and GitLab integration to unify those workflows. The GitHub repository below contains a server with endpoints to handle all of the requests for a basic integration. Below are the use cases the script supports:

• Pushing Productboard features into a specific GitLab project (the project is chosen in the script) as issues that will include the feature’s name, description, and the Productboard URL.
• Once a feature is pushed from Productboard, a link to the GitLab issue is created in the push button within the GitLab integration task column and the feature details side pane.
• Changes to the status of the GitLab issue are shown in the GitLab integration column in Productboard.

In this article:

• Limitations
• Required tools
• Getting Started
  • Forking the GitHub repository
  • Deploying your repository to Heroku
• Adding the plugin integration with Postman
• Adding variables to your Heroku app
• Setup your GitLab webhook
• Next steps

Limitations

1. Features can only be pushed to a single GitLab project. In order to push to additional projects, this integration will have to be replicated or logic built into the integration to choose a specific project i.e. a custom field dropdown.
2. Features can only be pushed as issues.
3. Two-way sync is not implemented but can be enabled through the addition of webhooks in the script.

Required tools

This guide will be using the tools below to build the integration. If you need to sign up or create them, links are provided.

• Heroku account
• Postman account
• GitHub account

You will also need to create the following from Productboard and GitLab (instructions will be provided further down in the tutorial).

• Productboard’s API token
• GitLab webhook and Personal Access Token (api & read_api scopes)

Getting Started

Forking the GitHub repository

You can fork the GitHub repository by going to this link. From there, you will be able to name your repository and provide a description (optional).

Deploying your repository to Heroku

In this section, we will demonstrate deploying our repository onto Heroku so that it can listen to HTTP requests for us. Heroku is a simple and free Platform-as-a-Service (PaaS) that can do all the heavy lifting for us. Let’s begin.

1. Go to the bottom of your forked repository where the README is located and click on Deploy to Heroku.
   
   
2. If you are redirected to the registration page, sign up if you do not have an account, or sign in using the link at the top right of the page.
3. Once logged in, you will be sent to the Create New App page. Add a name for your application and click Deploy app. The app should be deployed in about 1-2 minutes.
   
   
4. To confirm the server is running, click on Manage App to be brought to your app’s homepage. Then click on Open app at the top right of the screen. You should now see a new web page with the phrase: “This is a Heroku server hosting our Productboard <> GitLab integration”.
   
   

   Note: You may see an error if opened too quickly - give it an extra few minutes to finish loading the server and try refreshing.

   With the app running on Heroku, we now have to make the app “ours” by creating the plugin integration (task column) in Productboard, adding API tokens, and enabling webhooks. Let’s start with the plugin integration.

Adding the plugin integration with Postman

To create a plugin integration, you need to send an HTTP request to a location on the internet that will respond correctly in order to authenticate the plugin integration. Luckily, your Heroku app is set up to respond correctly so we just need to send the request somehow.

Postman can be used in situations like these since it is a platform to easily send HTTP requests. We will use it to send a POST request to https://api.productboard.com/plugin-integrations with the following body:

{
"data": {
"integrationStatus": "enabled",
"type": "com.gitlab",
"name": "GitLab integration", 
"initialState": {
"label": "Push"
},
"action": {
"url": "https://your-heroku-app-name-here.herokuapp.com/plugin",
"version": 1,
"headers": {
"authorization": "MyAuthToken123456"
}
}
}
}

There are two parts of the JSON body that are important. First, the name of the task column that will be created for you in Productboard is determined by data.name. Second, the URL you will be sending the push requests to is data.action.url and has to be your Heroku app URL.

With that in mind, click the Run in Postman button located in the README of your GitHub repository. This link will provide you with a template of the POST request we need to send.

With Postman open, let’s run through a few more steps.

1. Click on the Productboard API Collection (#1 in the screenshot) and go to the Authorization section. Enter your Productboard API token into the Token section (#2 in the screenshot). Save this token somewhere secure since you will be using it in your Heroku app. For more information on how to create a new API token, go to our developer documentation.
   
2. Go to Create new plugin integration
   
   
3. Once there, go to the Body section. Now you will modify the data.action.url field to include your Heroku app URL (i.e. https://your-heroku-app-name.herokuapp.com) with /plugin at the end of it. And if you’d like the integration column name in Productboard to be different, edit the data.name field.
   
4. You can now hit Send. A 201 Created response should appear at the bottom with the following body:

   {
   "data": {
   "id": "9d1b978e-f682-46d6-a91e-a8414669be4e",
   "createdAt": "2022-06-16T03:43:03.957845161Z",
   "integrationStatus": "enabled",
   "type": "com.productboard.gitlab",
   "name": "Gitlab integration",
   "initialState": {
   "label": "Push"
   },
   "links": {
   "self": "https://api.productboard.com/plugin-integrations/9d1b978e-f682-46d6-a91e-a8414669be4e"
   }
   }
   }

5. With our plugin integration created, you should now see a new integration in the Task menu on the Features Board. Don’t push any features yet, as there are a few more steps left.

Adding variables to your Heroku app

With the plugin integration created, you can now update your Heroku app with our API tokens and integration IDs so the app knows where to send our requests.

In order to change these variables:

1. Go to your App in Heroku.
2. Click on Settings in the menu.
3. Click on Reveal Config Vars. You can now begin to add the following variables:

In order to get your GitLab Project ID, go to the home page of your Project in GitLab and copy the ID under the page title. Screenshot for reference:

Once the KEYs and VALUEs are entered, this is how your Config Vars menu should look:

Setup your GitLab webhook

The last step is to track the status of issues from GitLab in our plugin integration column. In order to establish the connection, we need to create a GitLab webhook and send the updates the webhook provides. In the script we provided, there is a route that handles all the webhook requests and updates the corresponding plugin integration connection. Below are instructions on setting up your webhook.

1. Go to your GitLab project home page and from the left-hand menu go to Settings > Webhooks.
2. In the URL field add your Heroku app link with /gitlab-webhook at the end. It should look like this: https://your-heroku-app-link.herokuapp.com/gitlab-webhook
3. Within the Trigger section, checkmark Issue events. You may have to uncheck Push events, since that is sometimes selected by default. SSL Verification can be left toggled on.
4. Click Add Webhook and you should be finished. A webhook should appear in your Project Hooks section at the bottom of the page.
   

Next steps

Now that you have your basic GitLab integration in place, you can now push your features from Productboard into a Gitlab project of your choice and track the status of those issues within Productboard. Go ahead and test out the integration by pushing a feature into Gitlab!

If you’d like, you can build off the script and add your own changes or improvements. A project selection could be implemented with a custom field dropdown or a 2-way sync through the use of webhooks.

If you have any feedback, feel free to email alex.degregori@productboard.com