HacknPlan can be integrated with GitLab to link your commits to the work items they are related to, allowing you to have a list of the changes to the code always at hand on the task detail panel. To be notified about the commits performed on your GitLab instance, a webhook needs to be configured pointing to our server, which will receive the data from push events and will analyze the commit messages looking for task IDs with the format “hnp-id” (this prefix can be modified in the integration settings).

Note: GitLab integration is available for Personal Plus and Studio users only.

The webhook can be created in two different ways: automatic and manual:

• The automatic method only works for the repositories hosted on GitLab.com (so far), but allows you to set the integration up just by entering your access token and selecting the desired GitLab project. Everything will be configured automatically, and in case you want to remove the integration, the webhook in GitLab will be removed too. We recommend this method if you are hosting your GitLab project in the cloud.
• The manual method consists of you configuring the webhook manually on your GitLab instance, following our instructions below. This is the only valid method for self-hosted instances.

Automatic integration

Go to the Administration → Integrations section from your project left menu and click on the New button on the GitLab panel, and then select Auto from the dropdown list:

A popup dialog is launched, asking for a personal access token. A personal access token is an authentication method needed to use the GitLab API on behalf of your user, so we can configure the webhook for you. You can create as many as you want from your profile settings in GitLab. Go to Settings → Access Tokens, and create a new token with the name HacknPlan, no expiration date and API access:

You can set an expiration date or revoke this token when you want, but recommend keeping it active, so we can safely remove the webhooks we create or other future features we add to our GitLab integration. Once created, you need to copy the generated token and paste it into the integration dialog in HacknPlan. Be careful, you won’t be able to access the token from GitLab again.

Note: Although OAuth2 based authentication is available for GitLab (the authentication method we use for the other integrations), we decided to go for the personal access token approach because the OAuth2 one does not work with accounts that use 2-factor authentication.

When you paste the access token into the field on the dialog, it will be validated and, if correct, a list of your GitLab repositories will be added to the dropdown below. Select your desired repository and click Save. Your integration is ready!

Manual integration

Go to the Administration → Integrations from the left menu of your project and click on the New button on the GitLab panel, and then select Manual from the dropdown list. This will generate a secret token that you will need to use to configure the webhook on GitLab:

If you close this window, you can always open it again by clicking on the Webhook button on the item created on the GitLab panel.

Now you need to create the webhook in GitLab with the provided information. Go to your project and click on Settings → Webhooks, click on Add new webhook and fill up the fields like in the picture below:

You just need to enter the URL and Secret token provided in the dialog, and the rest of the options will remain as they were by default. Click on Add webhook and you are good to go!

Testing the integration

Your integration is now configured, let’s check if everything is working fine. You need to push a commit that includes the reference to an existing HacknPlan task in the message, for instance:

This is a test for task hnp-2

Note: Use the reference prefix you set in the integration configuration.

When HacknPlan receives the notification of the push of that commit, the message is analyzed looking for references to work items, and the commit is added to all of them. Then, you can check the commits in the Source Code section of the task detail panel. And remember, clicking on each one of the commits will take you to the details in GitLab!