With the GitLab integration you see merge requests, pipelines, environments and commits right on your tasks in FeatValue. Your clients learn in plain words whether their change is in progress, on staging for testing or live.
What the GitLab integration is for
Software companies and web agencies keep getting the same question: “Is this online yet?” With the integration, FeatValue answers it on the task:
- Branches, commits and merge requests with the task ID appear on the matching task.
- Pipelines and deployments show whether the change has been tested and which environment it has reached.
- FeatValue writes important steps as comments to the task history.
- For each project you decide what your clients see of it.
- You start manual jobs, such as a deployment, right from FeatValue.
For an overview, see the page about the GitLab integration.
Requirements
- a FeatValue account for your company with at least one client and project (see Creating projects)
- GitLab on gitlab.com or as a self-managed instance, reachable via https
- at least the Maintainer role in the GitLab projects you want to link. This allows FeatValue to create the webhook.
Connect GitLab
-
Open the app
Click
Apps in the left sidebar, choose
GitLab and click
Install (see
Connecting apps). The page
Connect GitLab appears with the question
Where is your GitLab?
-
gitlab.com
Choose gitlab.com and click Continue. Sign in to GitLab and allow access. This gives FeatValue access to your projects.
-
Self-managed GitLab instance
Choose Self-managed GitLab instance. Enter the https address under Instance address, for example https://gitlab.example.com, and a token under Personal access token. Click Continue.
Which token do I need for a self-managed instance?
Create the token in GitLab under Preferences › Access tokens:
- Scope:
api. Read-only scopes such as read_api are not enough, because FeatValue creates webhooks and starts manual jobs.
- Role: The token's user needs at least the Maintainer role in the projects.
- Expiration date: Once the token expires, no new data arrives. Create a new one and connect GitLab again.
Ideally use a dedicated user or a group token for the integration. That way it does not depend on one person's account.
Link a repository to a project
Each repository belongs to exactly one FeatValue project. Only linked repositories reach FeatValue.
-
Open Link repositories
Open
Settings › Company › Integrations & apps and choose
GitLab (see
Connected apps). The page is called
Link repositories.
-
Find the repository
Your repositories are listed under Repositories in GitLab. Use Search repository to narrow the list.
-
Choose a project and link
Next to the repository, choose the FeatValue project and click Link. FeatValue creates a webhook in GitLab and catches up on the last few days.
All links are listed under Linked repositories. The column Updates shows Instantly via webhook or Every 10 minutes. Use Change to pick a different project, and Unlink to remove the link; FeatValue then deletes the webhook again.
Using the task ID correctly
Every task in FeatValue has an ID, for example abc123-4. You find it on the task. Put this ID in one of these places:
| Where |
Example |
| Branch name |
abc123-4-contact-form |
| Commit message |
abc123-4 Make phone number required |
| Title or description of the merge request |
Contact form: make phone number required (abc123-4) |
- Upper and lower case do not matter, and a leading
# is allowed.
- If the ID is in the branch name, only the commits that exist solely on this branch count. Commits from the default branch that come along when branching off do not appear on the task.
- Commits on other branches only appear if the ID is in their commit message.
- The ID only applies within the linked project. FeatValue never assigns repositories that are linked to another project or not linked at all.
- Pipelines and deployments belong to the task if they run for one of its branches, commits or merge requests.
What appears on the task
The task shows the Development section with one compact line, for example: MR !12 merged · Pipeline passed · Deployed to Staging. Click Show details to expand:
- Pipelines with stages and jobs and their status
- Environments with a link to open them, for example Staging and Production
- Merge requests, Branches and Commits
What appears in the project
In the project, the Development section shows the environments with their latest deployment and the latest pipeline on the default branch. Click Show all pipelines to see the Latest pipelines. This is also where you find the project's Settings.
What do clients see?
In the Settings of the Development section in the project, choose under What do clients see?:
| Setting |
Your client sees |
| Nothing |
no information from GitLab |
| Simple status |
one sentence without technical terms: In progress, Rolled out to Staging with the link test it here, or Live with the link take a look |
| Details |
the sections you tick under Details for clients: commits, branches, merge requests, pipelines, environments and history comments |
People in your company who may edit the project can change this setting. How your client then tests and approves is explained under Review and acceptance.
FeatValue writes important steps as comments to the task history. Under Activity comments on the task you choose for each project which events create a comment:
- Merge request merged
- Pipeline passed
- Pipeline failed (with failed jobs)
- Deployed to environment
Deselected events still update the status on the task but no longer create a comment. Whether your client sees the comments depends on the setting under What do clients see?.
Run jobs from FeatValue
Starter
You start manual jobs of your pipeline, for example deploy-production, right in FeatValue. This is available from the Starter plan (see Plans).
-
Allow jobs
In the project, open the Settings of the Development section. Under Run jobs from FeatValue you find the manual jobs GitLab has reported so far. Tick the jobs that should appear in FeatValue and click Save.
-
For clients too
If your client should be able to start the selected jobs, tick Clients may run the selected jobs too.
-
Run a job
When an allowed job is waiting for its manual start, it appears with the button Run. After the click, FeatValue shows Started, and you follow the rest on the pipeline.
If it says No manual jobs reported yet., no pipeline with a manual job has run yet. As soon as GitLab reports one, you can allow it.
Security
- Only linked repositories: FeatValue only reads repositories you have linked to a project, and assigns task IDs only within that project.
- No code: FeatValue does not store files from your repository, only information about branches, commits, merge requests, pipelines and environments.
- Verified webhook: Each webhook gets its own secret token. FeatValue only accepts calls that send this token.
- Your rights in GitLab: FeatValue works with the rights of the sign-in or the token. It can only start jobs you have allowed.
- Unlink at any time: Unlink removes a link, and FeatValue deletes the webhook.
Troubleshooting
My repository is missing from the list
FeatValue only shows repositories in which you have at least the Maintainer role. Check your role in GitLab or search for the name with Search repository.
The webhook could not be created
The link then shows Every 10 minutes instead of Instantly via webhook. In this case FeatValue checks GitLab every 10 minutes, so nothing gets lost, it just arrives later. Common causes: you lack the Maintainer role, or your GitLab instance may not send requests to the internet. Check this, then click Change and Link again.
Nothing appears on the task
- Is the repository linked to the project the task belongs to?
- Is the full task ID in the branch name, the commit message or the merge request?
- Without a webhook, it takes up to 10 minutes for new data to arrive.
GitLab did not accept the token
Check the instance address, the token and the scope api. The token must not have expired.
A job cannot be started
Running jobs is available from the Starter plan. The job also has to be allowed in the project settings and currently waiting for its manual start. If Could not be started appears, check in GitLab whether the sign-in may still start the job.