Connect to GitLab

Connect GitLab, cloud or self-hosted, to your workspace with an access token, pick the projects Taskie should follow, and see merge requests, branches, commits and issues that mention a task ID in that task's Development section.

The GitLab connection keeps your code projects and tasks side by side. A workspace admin enters the GitLab address and an access token and ticks the projects to follow; from then on, every merge request, issue, branch or commit that mentions a task ID such as TASK-12 is listed in that task's Development section. Both gitlab.com and self-hosted instances are supported.

This connection exists only at the workspace level and works for every member; there is no personal GitLab connection. Linking, the Development section, pipelines and completion on merge behave just as described in Connect to GitHub. This guide focuses on what's different for GitLab and summarizes the shared rules.

Before you start

App Center
Find GitLab in the App Center, under Development & DevOps
  • You need to be an owner or admin of the Taskie workspace.
  • In GitLab, create a personal access token with the api scope. Taskie uses it to add webhooks to your projects, leave comments, and create branches or issues.
  • Taskie only lists projects where the token's account has at least the Maintainer role.
  • A self-hosted server must be reachable from the internet over HTTPS; internal or private addresses are rejected. Your GitLab must also be able to send webhook requests to Taskie.
  • The GitLab connection counts as one of the workspace's integrations, and how many you can have depends on your plan.

Create the connection

GitLab card in the App Center
The GitLab card in the App Center; the connection form is on the app's page
  1. In GitLab, create a personal access token with the api scope and copy it.
  2. In Taskie, open the App Center from settings, click the GitLab card and choose the Workspace tab.
  3. In Base URL, enter your GitLab server's address. For gitlab.com you can leave it empty.
  4. Paste the token into Access token and, if you like, give the connection a Label.
  5. Click Connect GitLab. Taskie checks the token and its api scope before saving, then fetches your project list in the background.

If the connection isn't created: the error message tells you why: the token has expired or been revoked ("GitLab rejected this token"), it lacks the api scope, or Taskie couldn't reach the GitLab address. When a token expires, just connect again with the same GitLab account and the same address; Taskie replaces the token on the existing connection instead of creating a second one.

Pick projects and webhooks

Unlike GitHub, a GitLab token reaches every project its owner maintains, so newly found projects start untracked and you choose which ones Taskie follows. Click Manage on the connection card and, under Repositories:

  • Tick the projects Taskie should follow and click Save selection. On long lists, the Filter projects box helps you find a project.
  • Taskie adds a webhook to each ticked project and removes it from the projects you unticked. You don't need to create webhooks in GitLab yourself; the Inbound URL is shown only so you can check it.
  • If adding a webhook fails on a project, it shows No webhook with that project's error underneath. After fixing the cause (for example, giving the token's account the role it needs), click Resync to fetch the list again and re-add any missing webhooks.

The rest of the Manage sheet works as it does for GitHub: the What Taskie listens for switches (Merge requests, Issues, Pipelines and workflow runs, Branch and commit pushes, Link tasks mentioned by ID and Move and complete tasks), the Rules section, and Recent events, which shows skipped events with their reason and puts a failed event back in the queue with Retry. The connection card shows Working, Needs attention or Disconnected with the reason and the time of the last event.

Automatic linking and the Development section

Task details window
The task details window. Once GitLab is connected, a Development button appears here

Write the task ID in the branch name, the commit message, the merge request title or description, or the issue title or description. The forms TASK-12, #TASK-12 and CU-TASK-12 are accepted, and lowercase IDs and non-Latin digits are read too. For example, a branch named feature/TASK-12-login is linked to task TASK-12 automatically. Links are only made from tracked projects and only to tasks in the same workspace.

  • Groups: the Development section lists items under Pull & merge requests, Branches, Commits, Issues and Other links, and shows the latest pipeline result next to a linked merge request or branch. Deleting a branch in GitLab is recorded on that branch's link too.
  • Work on this task: Branch name, a New branch command, Commit message and the Close on merge phrase are ready to copy.
  • Add link: paste the URL of a GitLab merge request, issue or commit (URLs containing /-/merge_requests/, /-/issues/ or /-/commit/) to link it by hand.
  • Create branch and Create issue: create a branch or an issue on one of the tracked projects; it's linked to the task right away. If you haven't picked any projects yet, the create dialog asks you to pick them in the connection's Manage sheet.

Completing and moving tasks automatically

A plain mention of the ID only links the task. A task is completed when a merge request is merged and its title or description has the ID right after one of these closing keywords: close/closes/closed, fix/fixes/fixed or resolve/resolves/resolved. You can list several IDs with commas or "and", as in Closes TASK-12, TASK-15 and TASK-18.

  • Optional rules: Complete tasks named after a closing keyword in a push to the default branch and Complete a task when a merged branch is named after it, even without a closing keyword are in the Rules section. Both are off by default.
  • Move with brackets: TASK-12[In Review] moves the task to that project status; don't put a space between the ID and the brackets.
  • Conditions: the Move and complete tasks switch must be on, and if the task's dependencies or the project's status workflow don't allow the move, the task stays where it is.

What Taskie sends to GitLab

The first time Taskie links a merge request or issue to a task, it leaves a short comment with the task ID and a link to the task. The rule Comment on a pull request, merge request or issue when Taskie links it to a task controls this and is on by default; the task title is only included if you turn on Include the task title in that comment. Beyond that, Taskie only creates the branches and issues you ask for from the Development section, and it never changes the state of a merge request or issue.

Activity, notifications and disconnecting

New links, removed links and state changes of linked items are recorded in the task's activity, labelled GitLab. The task's assignee and creator are notified when a linked pipeline fails, a linked issue is opened, or a merge completes the task. Set how these reach you in Set up notifications and reminders.

To disconnect, click Disconnect on the connection card; only a workspace owner or admin can do this. Disconnecting removes Taskie's webhooks from your projects and stops events, but the links already on tasks stay.

Common mistakes

  • A token without the api scope, or an expired token. Connect again with a new token to update the same connection.
  • A project missing from the list. The token's account needs at least the Maintainer role on it; then click Resync.
  • Expecting links from a project that isn't ticked. New projects aren't followed until you pick them.
  • Writing the closing phrase only in a commit message. It must be in the title or description of the merged merge request, unless the default-branch push rule is on.

Next step: if you also use GitHub, see Connect to GitHub. For programmatic access to Taskie, review API access and tokens.

Was this article helpful?