GitLab integration

What it does

The GitLab integration lets your agency drive every client's GitLab project from a single workflow. Connect a client's GitLab.com account or self-managed instance once and TaskJuice can read projects, file issues, open and label merge requests, and react in real time when commits land, issues change state, or merge requests move through review. Each connection carries a host field so the same bundle covers GitLab SaaS (gitlab.com) and self-managed installations (gitlab.acme.com) without bespoke routing.

Connect a GitLab account

1. Open your workspace in TaskJuice and navigate to Connections.
2. Choose GitLab and click Connect.
3. Enter the host of the client's GitLab instance. Use gitlab.com for GitLab SaaS, otherwise the self-managed hostname (e.g. gitlab.acme.com).
4. Sign in with the GitLab user whose projects you want to manage on behalf of your client.
5. Approve the requested scopes (api for the full REST surface, read_user to verify the connection, read_repository and write_repository so workflows can list, branch, and open merge requests).
6. TaskJuice returns you to the workspace with the connection ready to use in any workflow.

To revoke access, the connected user can open https://{host}/-/user_settings/applications, find the TaskJuice authorization, and revoke it. For self-managed instances, an instance admin can also revoke under Admin Area, Applications.

Triggers

• gitlab/push-event fires when commits are pushed to a project branch or tag. Use it to drive deploy gates, changelog generation, or downstream CI.
• gitlab/issue-event fires when an issue is opened, updated, closed, or reopened. Filter on object_attributes.action to scope the workflow to a specific lifecycle transition.
• gitlab/merge-request-event fires when a merge request is opened, updated, approved, merged, closed, or reopened. Use it to coordinate review automation, post-merge follow-up, or release notes.

GitLab webhooks authenticate each delivery with the X-Gitlab-Token header (a long-lived shared secret you configure per project). TaskJuice rejects deliveries whose token does not match the value provisioned when the trigger was published.

Actions

• gitlab/get-current-user returns the authenticated GitLab user. Use it as a connection sanity check after authorization.
• gitlab/list-projects lists projects the authenticated user can access, with keyword search and page-based pagination.
• gitlab/get-project fetches a single project by numeric ID or URL-encoded namespace/path.
• gitlab/create-issue files a new issue in a project, with labels, assignees, confidentiality, and due-date fields.
• gitlab/list-issues lists issues in a project, filtered by state, label, or updated-after window, with page-based pagination.
• gitlab/create-merge-request opens a merge request from a source branch to a target branch, with squash, source-branch removal, assignee, and label options.

Known limitations

• GitLab.com enforces per-user and per-project rate limits on the REST API. When the upstream returns a 429, TaskJuice surfaces it as a retryable rate-limit error and respects the recommended backoff window.
• The X-Gitlab-Token shared secret is a long-lived static value, not a per-request HMAC. Treat it like an API key: rotate it whenever a project owner changes hands or a token is suspected of exposure.
• Project ID inputs accept both numeric IDs (e.g. 42) and URL-encoded namespace/path (e.g. acme%2Fbackend). When templating the path form from prior step output, URL-encode the slash before passing it through.
• Self-managed GitLab instances must be reachable from the public internet for outbound API calls and inbound webhook delivery to work. Air-gapped or VPN-only instances require a bespoke connector.
• GitLab's webhook delivery is at-least-once. Workflows that must process each event exactly once should dedupe on object_attributes.id for issues and merge requests, or on the commits[].id for push events.