When you need this guide
Git-Zen prefers OAuth 2.0 for GitLab connections — it's automatic and refreshes on its own. Use a Personal Access Token (PAT) instead when:
- Your GitLab admin has disabled OAuth for third-party applications.
- You want Git-Zen to run under a service account rather than a personal account.
- You're connecting Git-Zen to a self-hosted GitLab instance behind a firewall.
- You're switching back to PAT after an OAuth user lost access to a project.
Required scopes
Git-Zen needs the following scopes on your PAT. Anything more is unnecessary; anything less and parts of the integration will fail silently.
| Scope | Why Git-Zen needs it |
|---|---|
| api | Full read/write access to the GitLab API — create issues from Zendesk tickets, sync labels, milestones, comments, and field updates. |
| read_repository | Read commits referenced from Zendesk tickets via gz# tags. |
api grant write access?
GitLab's api scope is broader than ideal — it does include write. That's a GitLab limitation, not a Git-Zen design choice. The narrower read_api scope alone would mean Git-Zen could read your data but never create or update issues from Zendesk, which defeats the integration.
Step-by-step
Open Access Tokens in GitLab
On gitlab.com (or your self-hosted instance), click your avatar in the top-left and select Edit profile. Then click Access Tokens in the left sidebar.
Create a new token
Click Add new token. Fill in:
- Token name:
Git-Zen Integration - Expiration date: 1 year out (or as long as your security policy allows)
Select scopes
Check the boxes for:
- api
- read_repository
Leave everything else unchecked.
Copy the token immediately
Click Create personal access token. GitLab shows the token once at the top of the page, with a copy button. Copy it to your clipboard or a password manager right now — if you navigate away without copying, you have to start over.
Paste the token into Git-Zen
Inside Zendesk, open any ticket and find the Git-Zen sidebar. Then:
- Click the gear icon → Settings
- Open the Authentication section
- Switch from OAuth to PAT
- Paste the token and (if self-hosted) confirm your GitLab Base URL
- Click Save
Git-Zen will validate the token immediately. If something is wrong with the scopes, the validator tells you which scope is missing.
Group access tokens (GitLab Premium / self-hosted)
If your GitLab instance supports Group access tokens (Premium or self-hosted), prefer those over personal tokens for service-account-style usage.
They follow the same scope requirements but don't break when an employee leaves. Create one at
Group settings → Access Tokens, give it the Maintainer role, then paste it into Git-Zen the same way.
Troubleshooting
"401 Unauthorized" after pasting
- Confirm you copied the token without surrounding whitespace.
- If self-hosted: confirm the Base URL exactly matches your GitLab instance (no trailing slash issues).
- Confirm the token hasn't expired.
"403 Forbidden" or "Insufficient scope"
- Your token is missing the
apiscope. Recreate it with both required scopes. - The token's owner doesn't have at least Maintainer access to the project. Check project member permissions in GitLab.
Comments aren't syncing back to Zendesk
- This is usually a webhook issue, not a token issue. Check the Webhooks section in Git-Zen Settings — ensure the GitLab project webhook is still present and wasn't deleted.
- For self-hosted GitLab: verify Git-Zen's outbound IP is allowlisted on your firewall so webhooks can reach us.
The token expired
GitLab emails you 7 days before expiration. Repeat steps 1–5 to create a new one and paste it into Git-Zen Settings. Your settings, links, and history stay intact during the rotation.
Security best practices
- Use a Group access token over a personal one when available.
- Use the shortest expiration your security policy allows.
- Use only the required scopes from the table above — never grant additional scopes.
- Store the token in a password manager or secret vault, not in plain text.
- Rotate annually even if not required.
Other auth setup guides
GitHub Personal Access Tokens → · Azure DevOps Personal Access Tokens → · Back to Git-Zen for GitLab →