GitLab Integration
TwoWeeks can pull issues from GitLab (SaaS or self-hosted) and push final estimates back as labels.
Supported GitLab Deployments
Section titled “Supported GitLab Deployments”| Type | URL format | Auth |
|---|---|---|
| GitLab SaaS | https://gitlab.com | Personal Access Token |
| Self-hosted | https://gitlab.your-company.com | Personal Access Token |
Prerequisites
Section titled “Prerequisites”- In GitLab, go to Settings → Access Tokens (or Preferences → Access Tokens)
- Create a Personal Access Token with the
apiscope (orread_apifor read-only import) - Copy the token — it is shown only once
Connecting to GitLab
Section titled “Connecting to GitLab”- As a session host, click Import from GitLab in the sidebar
- Fill in the connection form:
| Field | Description |
|---|---|
| GitLab URL | Full URL to your GitLab instance (e.g. https://gitlab.com) |
| Personal Access Token | Your PAT with api scope |
| Allow insecure | Enable for self-signed certificates on private instances. Your administrator can disable this (INTEGRATION_ALLOW_INSECURE_TLS=false); you’ll then see a warning and the certificate is always checked |
If your organisation uses a custom CA certificate, the server administrator can configure it via CA_BUNDLE_PATH or the --ca-bundle CLI flag.
- Click Test connection & continue
Security Note
Section titled “Security Note”Your GitLab PAT is encrypted at rest in the database when the server is configured with an ENCRYPTION_KEY environment variable. Without it, the token is stored in plaintext (a warning is logged at startup). The token is never sent to connected developers — all GitLab API calls go through the backend.
Estimate Labels
Section titled “Estimate Labels”TwoWeeks reads and writes estimates using GitLab labels. The default label prefix is Estimate. For example, a story-point estimate of 5 appears as a label Estimate::5.
You can change the label prefix per session (e.g. SP, StoryPoints) — this is configured during the connect step or from session settings.
When importing issues, TwoWeeks reads the current estimate label (if any) and shows it in the import list. When pushing an estimate back:
- Any existing label with the configured prefix is removed
- The new estimate label (
{prefix}::{value}) is added - A comment is posted:
TwoWeeks estimate: **5**
Other labels on the issue are left untouched.
Filtering Issues
Section titled “Filtering Issues”After connecting, use the filter panel:
| Filter | Description |
|---|---|
| Project | Select a GitLab project |
| State | Opened, closed, or all |
| Milestone | Filter by milestone |
| Labels | Filter by existing labels |
| Text search | Free-text search across title and description |
Importing Issues
Section titled “Importing Issues”- Set up filters and click Search issues
- Review the results — you will see title, state, existing estimate, and labels for each issue
- Select issues to import (or use Select all)
- Click Review import
- Confirm and click Import N tickets
Imported tickets appear in your session ticket queue. Each ticket stores its GitLab project ID and issue IID for later updates.
Pushing Estimates Back to GitLab
Section titled “Pushing Estimates Back to GitLab”When you finalize an estimate for a GitLab-imported ticket, TwoWeeks pushes the estimate automatically:
- The old estimate label is removed
- The new estimate label is added
- A comment records the estimate
You can also push manually by clicking the Update in GitLab button on the finalized ticket card.
Resyncing a Ticket
Section titled “Resyncing a Ticket”If a GitLab issue changes after import, the host can pull the latest version:
- Open the ticket’s details panel (double-click the ticket)
- Click Resync next to the GitLab issue reference
- The title, description, labels, and current estimate update from GitLab
Host-Level Defaults
Section titled “Host-Level Defaults”From the Account page, you can save GitLab connection defaults that pre-fill when you create any new session:
- GitLab URL and PAT
- Default project ID
- Default label prefix
- Default label, state, search, and milestone filters
These are stored securely (the PAT is encrypted) and can be overridden per session. The saved PAT is never sent back to your browser: the form shows Token saved · Replace, and the importer leaves the token field empty (“Saved token will be used”) — the server uses the saved PAT for the same GitLab URL. Changing the saved URL without entering a new PAT clears the old one.
Troubleshooting
Section titled “Troubleshooting”| Error | Fix |
|---|---|
| Could not reach GitLab | Check the URL and network. Error messages are deliberately generic — your administrator can see the detailed reason in the server log |
| URL is not allowed | The server’s integration policy blocks that address (for example cloud-metadata addresses, or localhost unless your administrator allow-lists it with INTEGRATION_HOST_ALLOWLIST) |
| GitLab rejected the credentials | Verify the PAT is correct and has api scope. Check that the token has not expired |
| Could not verify GitLab’s TLS certificate | Enable “Allow insecure” for self-signed certificates (if your administrator allows it), or ask your admin to configure CA_BUNDLE_PATH |
| Search returns no results | Check project selection and filters. Try broadening the search |
| Update fails | Verify the issue still exists in GitLab. Check that the PAT has write access |
| Resync fails | The issue may have been deleted or the connection may have expired — reconnect to GitLab and try again |