API Integration

Overview

The GitLab API integration connects a TestKase project to GitLab Issues so you can search issues, link them to your test cases as requirements, and keep a lightweight traceability bridge between test management and your development workflow. When you link a test case to a GitLab issue, TestKase posts a comment on that issue listing the linked test cases, giving developers visibility into test coverage. Issue status is pulled from GitLab on demand whenever you refresh it.

This integration is especially valuable for teams that manage their product backlog in GitLab and want to maintain traceability from requirements through test cases.

Prerequisites

Before setting up the GitLab integration, make sure you have the following ready:

1. A gitlab.com Personal Access Token with the api scope.
2. Your GitLab username.
3. Project Admin or Owner role in the TestKase project. See User Permissions for details.

Setup

In TestKase project settings, requirement and defect integrations are configured separately. To search and link GitLab issues from your test cases, configure the requirement integration:

1. In TestKase, open the Requirement Integration page for your project.
2. Under API Integrations, click Connect on the GitLab card.
3. Enter your GitLab Username.
4. Paste your Personal Access Token.
5. Choose the Account Type -- Personal for your own projects, or Organization to pick a GitLab group first. (The radio button is labelled Organization; for GitLab it means a group.)
6. Click Next. If you chose Organization, select the group.
7. Select the project from the dropdown, then click Save.

Defect integration is configured the same way from the Defect Integration page.

Choosing Personal vs Organization Correctly

The Account Type decides where TestKase looks:

• Personal lists the projects in the namespace of the username you entered. Projects that live in a group are not returned, even though your token can see them -- the connection stops with "Failed to connect or there are no GitLab projects available. Please verify your credentials."
• Organization first lists the GitLab groups you are a member of at Guest level or above, up to 100 of them, then lists the projects inside the group you pick. If the list comes back empty you see "No organizations found for this account".

If your work lives under a group or subgroup, choose Organization. Pick the subgroup itself if that is where the project lives -- selecting a parent group lists only the projects directly inside it, not the ones inside its subgroups. Subgroups appear in the group list as entries of their own.

The Project Dropdown Shows One Page

TestKase asks GitLab for a single page of projects, so the dropdown holds the first 20 (GitLab's default page size). The label above the dropdown tells you how many were returned. If it says 20 and your project is missing, pick a narrower group and reconnect.

One GitLab Project per TestKase Project

A GitLab project can be connected to one TestKase project at a time. If it is already connected somewhere else, saving fails with "This gitlab-api project is already configured with another testkase project." Reset the connection on the other TestKase project first.

The Token Must Be Able to Comment

Linking a test case posts a coverage comment on the GitLab issue in the same operation. If the token cannot write to the project, the link itself fails -- nothing is saved and you see an error. This is why the token needs the full api scope; the read-only read_api scope is not enough.

Linking Requirements

Once connected, you can search your GitLab project's issues from within TestKase and link them to test cases as requirements. There is no automatic bulk import and no continuous background sync -- issues are searched on demand and linked individually.

How Linking Works

• Search on demand -- From a test case, search your connected project's issues by keyword. TestKase queries GitLab live and returns matching issues (IID, title, and state). Results arrive 10 per page, and your typing is sent about 0.4 seconds after you stop. The picker's column sorting reorders only the page you are looking at, not the whole result set.
• Browsing with an empty search -- With no keyword typed, TestKase lists the project's issues newest first, both open and closed. Typing a keyword switches to GitLab's project search.
• Link an issue -- Select an issue to link it. The issue title is stored as the requirement title and the issue IID is stored as a clickable reference.
• Coverage comment -- When you link a test case to a GitLab issue, TestKase posts a comment on that issue listing the linked test cases. Linking or unlinking additional test cases updates or removes that comment. This is the only change TestKase writes back to GitLab. Coverage comments are posted only by the API Integration -- projects connected through the Chrome Extension do not post comments back to GitLab.

Linked Requirement Behavior

• Linked requirements display a GitLab badge showing the issue IID. Clicking the badge opens the GitLab issue in a new tab.
• GitLab remains the source of truth for the linked issue's title and state.
• You can link test cases and defects, add attachments, and assign requirements to folders within TestKase -- these fields are managed locally.

Traceability from Test Cases

From the test case detail view, you can link test cases to GitLab issues. When a test case is linked, TestKase automatically posts a comment on the corresponding GitLab issue showing the linked test case details. This creates traceability from your GitLab backlog through to your test cases. Unlinking a test case updates or removes that comment accordingly.

Refreshing Issue Status

TestKase does not receive live webhooks or run a background sync. Instead, the state of a linked GitLab issue is refreshed on demand:

• Use the refresh action to pull the current state of a linked issue from GitLab into TestKase.
• The raw state value from GitLab is stored as-is. There is no automated transformation of GitLab labels or state into TestKase priority or status values.
• Refresh whenever you want the latest state -- for example, before reviewing coverage or building a report.

Refresh works on one test case at a time -- it updates the issues linked to the test case you have open. There is no project-wide refresh, so state across a large project is only as current as the last time someone refreshed each test case.

If the Token Expires or Is Revoked

The Personal Access Token is stored with the project's connection and used for every call. When it stops working, the symptoms differ by action:

To recover: generate a new gitlab.com token with the api scope, click Edit on the GitLab integration card, paste it, and save. Existing links, coverage comments and requirement records are untouched -- only the credential changes.

Defect Push

When available, defect push is planned to create a new GitLab issue from a TestKase defect, apply priority labels, and establish a cross-reference link between the two. This capability is not yet built.

Management

What Happens on Disconnect

If you disconnect the GitLab integration (from the requirement integration or defect integration configuration in project settings):

• Issue search and status refresh stop working for this project.
• Existing linked requirements are preserved in TestKase -- they are not deleted.
• Cross-reference badges on existing items continue to link to the GitLab URL.
• Comments already posted on GitLab issues remain in GitLab.
• You can reconnect to the same or a different project at any time.

Troubleshooting

▶I see an 'Authentication failed' error

This usually means your Personal Access Token is invalid, expired, or lacks the required scope. Verify the token in your gitlab.com profile settings and ensure it has the api scope. Tokens created on a self-managed GitLab instance will not work -- TestKase connects to gitlab.com only.

▶A linked issue's state looks out of date

TestKase does not sync state in the background. Use the refresh action on the linked issue to pull its current state from GitLab. If refresh fails, verify the integration is still connected and the token has not expired.

▶The coverage comment did not appear on my GitLab issue

TestKase posts a comment on the GitLab issue when you link a test case to it. If the comment is missing, confirm the token user has at least Reporter role (Developer or higher is recommended) on the GitLab project and that the integration is still connected.

▶Can I connect multiple GitLab projects to one TestKase project?

No. Each TestKase project supports one external integration connection at a time (per integration type). To work with multiple GitLab projects, create separate TestKase projects for each. This keeps the traceability clean and avoids cross-project confusion.

▶What happens to linked requirements if I disconnect?

Linked requirements remain in TestKase as regular requirements. They become fully editable and no further status refresh is possible until you reconnect. No data is lost during disconnection.

Questions

▶Is there another way to connect GitLab?

Looking for the browser-based approach? See the GitLab Chrome Extension for a lightweight alternative that works directly inside GitLab.

▶Refresh works but nothing syncs

A revoked or expired token does not make refresh fail visibly -- the state you see is simply the last one TestKase managed to fetch, which may be weeks old. If linked issue states have stopped moving, check the token before assuming the issues have not changed.

▶I already use the built-in requirements

If this project's requirement integration is currently Built-in, connecting GitLab deletes your built-in requirements. After you pick the GitLab project, TestKase shows a Data Loss dialog. Pressing Continue resets the existing integration first -- and resetting a Built-in integration permanently deletes every requirement and requirement folder in the project (on the Defect Integration page, every built-in defect). The deletion happens before the new connection is saved, so cancelling the rest of the wizard does not undo it. Export first, and read Built-in before you switch. Replacing one external connection with another does not delete anything -- only Built-in data is destroyed.