GitLab

The GitLab Application brings source-control, review, CI, and delivery evidence from GitLab into the same Hamstik Development experience used by other source control Applications. GitLab remains the system of record. Hamstik reads bounded metadata, associates it with existing Work Items, and links back to GitLab.

Overview

After an Organization administrator connects a GitLab instance and a Project administrator selects repositories, Hamstik can show:

GitLab project/repository identity, namespace, visibility, archive state, and default branch;
commits and their branches or references;
merge requests and current approvals;
pipelines, jobs, statuses, and artifact metadata;
environments and deployment attempts; and
automatic relationships between this evidence and existing Hamstik Work Items.

In GitLab, a source-code repository is called a project. In this guide, GitLab repository or GitLab project/repository distinguishes it from a Hamstik Project.

Availability and supported GitLab types

GitLab is a first-party Hamstik Application. It supports:

GitLab.com;
GitLab Self-Managed instances; and
GitLab Dedicated instances.

Self-Managed and Dedicated instances must expose a GitLab-compatible OAuth and REST API, use a canonical HTTPS URL in production, be reachable from the Hamstik server, and be able to reach Hamstik’s public webhook URL. A Self-Managed instance installed below a URL path is supported; enter the complete canonical base URL, including that path.

An Organization administrator manages connections. Project-level repository selection also requires permission to manage the relevant Hamstik Project Apps.

Prerequisites

Before connecting GitLab, make sure that:

you can create or obtain credentials for a GitLab OAuth application on the target instance;
the GitLab identity that authorizes Hamstik can read every intended GitLab repository;
that identity can create and manage project webhooks for selected repositories, normally by having Maintainer or Owner access;
the callback URL shown by Hamstik is registered exactly in GitLab;
the GitLab instance can send HTTPS webhooks to https://hamstik.com; and
Self-Managed network, proxy, certificate, and outbound-request policies permit the connection.

Permissions and OAuth scope

Hamstik uses GitLab’s OAuth 2.0 authorization-code flow with the api scope. GitLab defines api as broad authenticated API access. Hamstik needs it because the App both reads development evidence and creates, updates, and removes its own project webhooks. Hamstik does not use that grant to modify source code, merge requests, pipelines, deployments, or GitLab users.

The authorizing GitLab identity determines which repositories Hamstik can discover. GitLab authorization also controls whether Hamstik can read approvals, pipelines, environments, and deployments. Features unavailable in the connected GitLab tier or disabled by the instance cannot produce evidence in Hamstik.

See GitLab’s OAuth 2.0 documentation and project webhook API for the provider-side rules.

Connect GitLab

First create an OAuth application in the GitLab instance:

In GitLab, open the area where your administrators manage OAuth applications.
Create an application named for Hamstik.

https://hamstik.com/api/apps/gitlab/callback

Enable the api scope.
Copy the Application ID and secret. Treat the secret as a credential.

For local development only, use the callback URL for the local Hamstik origin.

Then connect it in Hamstik:

Open Organization Settings.
Select Apps, then GitLab.
Select Add connection.
Enter a recognizable connection name, the canonical GitLab base URL, the OAuth Application ID, and the OAuth secret.
Continue to GitLab, sign in as the identity that should authorize access, and approve the request.
Return to Hamstik. Hamstik validates the one-time OAuth state and code, verifies the connected identity, and starts repository discovery.

The connection card shows the GitLab instance, connected identity, repository counts, webhook health, queued or failed work, and synchronization timestamps. The Application ID, secret, OAuth code, access token, refresh token, webhook secret, and signing token are not returned to the browser after setup.

You can add separate connections for different GitLab instances or identities. Name them so Project administrators can choose the intended source.

Discover GitLab repositories

Hamstik pages through the GitLab projects visible to the connected identity, using GitLab’s maximum REST page size. Select Refresh repositories in Organization Settings after GitLab access changes. The refresh is asynchronous; reload the view to see the updated catalog.

Repository discovery records namespace, path, visibility, archive state, default branch, provider URL, and current accessibility. A repository that was previously discovered remains identifiable if access is later removed, but it cannot be newly selected until access returns.

GitLab’s REST pagination documentation describes the X-Next-Page and Link signals used by Hamstik.

Select GitLab projects

GitLab access and Hamstik Project selection are separate decisions:

the OAuth identity determines what the connection can discover; and
each Hamstik Project explicitly selects the GitLab repositories whose evidence belongs in that Project.

To select repositories:

Open a Hamstik Project.
Open Project Settings, then Apps.
Enable or choose the intended GitLab connection.
In GitLab repositories, search or move through the repository catalog.
Select up to 50 repositories and choose Save repositories.

Selections remain intact while paging or searching. An inaccessible repository that was already selected stays visible so an administrator can remove it. Removing it from the Hamstik Project does not delete it or change permissions in GitLab. Saving a new selection creates Hamstik-owned project webhooks before the selection becomes active, then queues initial synchronization.

Development evidence

Project Development presents provider-neutral evidence for all selected source-control repositories. GitLab uses native terms such as merge request, pipeline, and environment, while sharing the same cards, statuses, timestamps, actors, and provider-link behavior as other Hamstik SCM Apps.

The initial and reconciliation fetch is intentionally bounded per selected repository:

Evidence	Current bound
Default-branch commits	Most recent 100
Merge requests	Most recently updated 100, including open, closed, and merged
Commits for each synchronized merge request	Up to 100
Pipelines	Most recent 100
Jobs for each synchronized pipeline	Up to 100
Environments	First 100 returned by GitLab
Deployments per environment	Most recent 25

Push webhook payloads are persisted before reconciliation so commits on a non-default branch are not lost from Hamstik’s evidence when GitLab sends them. Artifact metadata includes the name and size exposed by GitLab; Hamstik does not copy artifact binaries or CI logs.

Link activity to Work Items

Hamstik recognizes complete Work Item references in branch names, commit messages, merge-request titles, merge-request descriptions, and pipeline references. Matching is case-insensitive and uses the same hyphenated key form as Hamstik’s other source-control Apps:

WEB-42
feature/WEB-42-retry-pipeline

A reference links only when:

the Work Item already exists;
its key belongs to the same Hamstik Project;
the GitLab repository is selected for that Project; and
all records belong to the same Hamstik Organization.

Duplicate references are harmless. A GitLab reference never creates a missing Work Item and cannot associate evidence with another Organization or Project. The Work Item Development area shows linked commits, merge requests, approvals, pipelines/jobs, and correlated deployments.

Webhooks

Hamstik manages one project webhook for each selected GitLab repository. It requests push, merge-request, pipeline, job, and deployment events. The precise public receiver accepts only POST requests for a known connection/repository receiver; callback and management routes retain normal Hamstik authentication.

On current GitLab versions, Hamstik configures and verifies GitLab’s signing token headers as an HMAC-SHA256 signature over the delivery ID, timestamp, and raw body. The timestamp must be within five minutes. For older GitLab instances that reject the signing-token field, Hamstik falls back to GitLab’s legacy X-Gitlab-Token verification. In both modes, unauthenticated or malformed deliveries are rejected before storage.

An accepted delivery is durably stored, deduplicated within the installation, and queued before Hamstik acknowledges it. Processing is repeat-safe. A worker persists normalized evidence and marks the inbox event processed atomically with job completion. Failed work retries with backoff; terminal failures are retained for troubleshooting and audit.

See GitLab’s webhook documentation and webhook event reference.

Synchronization and reconciliation

Webhooks provide timely notification but are not the only source of truth. Hamstik also performs initial synchronization, periodic repository discovery, selected-repository reconciliation, and webhook repair. This repairs missed events after Hamstik downtime, GitLab outages, delayed deliveries, or worker restarts.

Use Sync now from Organization Settings to reconcile all selected repositories on that connection. At Project level, Sync now queues only the repositories selected through that particular Project binding. Repeated work may be deduplicated while already pending.

GitLab rate limits and retry guidance are preserved as a connection-wide cooldown so concurrent jobs do not continue hammering the provider. Temporary provider, network, and lock-contention failures retry with bounded backoff.

Connection health and troubleshooting

The connection card combines credential state with operational evidence. It does not show Connected merely because an OAuth token exists.

State	Meaning and response
Healthy	Credentials, recent operations, and desired webhooks have no detected problem.
Sync needs attention	One or more jobs failed or a desired webhook is in a problem state. Review the detail, correct access, and run Sync now.
Reauthorization required	The grant was rejected, expired without a usable refresh grant, or was revoked. Select Reauthorize.
Insufficient permissions	The identity cannot read or manage a required GitLab resource. Check repository role and OAuth scope.
Rate limited / synchronization delayed	Hamstik is waiting for GitLab’s retry window before processing queued work.
Unreachable / TLS error	GitLab could not be reached safely. Check DNS, HTTPS certificates, proxy, and firewall policy.
Disabled	The Hamstik connection is locally disabled and does not schedule provider work.
Not yet checked	Complete authorization or use Test connection.

Authorization does not complete

Confirm that the callback URI matches exactly, the OAuth application enables api, the connection uses the canonical instance URL, and the authorization is completed by the same Hamstik user who started it. OAuth state is single-use and expires, so start again rather than reusing an old callback.

A repository is missing

Confirm that the connected GitLab identity is a member of the GitLab project/repository, select Refresh repositories, wait for queued work, then reload the Project catalog. Clear any search filter and check the next page.

Saving a repository fails at webhook setup

The identity must be able to manage project webhooks, normally as a Maintainer or Owner. Check that GitLab can accept the Hamstik HTTPS receiver and that the instance supports either signing tokens or legacy secret tokens. Hamstik does not activate a new repository selection if its required webhook cannot be established.

Activity is missing

Check that the repository is still selected and accessible, then inspect failed and pending counts, the last event received/processed times, and the last successful synchronization. Select Sync now after correcting the provider problem. Work Item association additionally requires a valid full Work Item key in one of the supported fields.

Approvals are missing

Confirm that the GitLab tier and connected identity expose the merge-request approvals API. A tier without that API can still synchronize merge requests and the rest of the supported development evidence. If that optional API becomes temporarily unavailable, Hamstik preserves approvals it recorded previously rather than treating the unavailable response as an authoritative empty list.

Disconnect or remove

Selecting Disconnect asks for confirmation. Hamstik then fences queued work, removes active Project bindings, attempts to remove Hamstik-owned project webhooks, requests OAuth token revocation, and deletes encrypted connection secrets. It does not delete the GitLab OAuth application registration or any GitLab repository, commit, merge request, pipeline, environment, or deployment.

Historical normalized Development, delivery, Work Item-link, and audit evidence remains under Hamstik’s retention rules. Current connection provenance is cleared. If provider authorization was already revoked, Hamstik records hooks it could not remove for administrator follow-up.

Security and data handling

OAuth state is random, hashed at rest, short-lived, bound to the Hamstik user and installation, and consumed once.
OAuth client secrets, access tokens, refresh tokens, and webhook secrets use encrypted server-side App secret storage.
Access and refresh-token rotation is serialized per installation so two workers cannot reuse a rotated refresh token.
OAuth codes, tokens, Authorization headers, webhook secrets, and complete callback query strings are not written by the Application to its logs or returned in diagnostics.
Provider URLs are restricted to HTTP for local development and HTTPS in production, reject embedded credentials, and are revalidated against resolved addresses and redirects to block unsafe outbound access.
GitLab IDs are always scoped by Hamstik Organization and installation; GitLab IDs alone are not globally trusted.
Provider payloads are size-bounded, retained only for the configured inbox window, and normalized into the shared Development and delivery models.

Hamstik stores metadata needed for discovery, health, synchronization, audit, Project Development, and Work Item Development. Repository contents beyond the bounded commit metadata, CI logs, artifact binaries, source files, and GitLab credentials remain in GitLab.

For related concepts, see Applications, Projects, Work Items, Users & permissions, and the Roles & permissions reference.