Self-Hosted GitLab Setup

Git-Zen supports GitLab.com and self-managed GitLab (Community or Enterprise Edition). GitLab.com is the default. It needs no extra setup. Follow the standard installation steps.

For a self-managed instance, Git-Zen sends all GitLab API requests to your instance URL. Git-Zen connects with a personal access token, not OAuth.

Note

Self-hosted GitLab is available on the Enterprise plan only. On other plans, Git-Zen always uses gitlab.com, even if an instance URL is saved. Contact support to move to Enterprise.

Before you begin

Make sure you have:

• The Enterprise plan.
• The base URL of your instance, for example https://gitlab.mycompany.com. It must start with https://.
• A GitLab account for Git-Zen. It needs the Maintainer role on the projects you want to connect, so that Git-Zen can create webhooks.
• Network access in both directions:
  • Git-Zen calls your instance from 52.202.91.72 on port 443. Allow this address in your firewall.
  • Your instance sends webhooks to https://api.git-zen.com on port 443.

Caution

Git-Zen accepts webhooks only from known IP ranges. Your GitLab server’s outbound IP address is not on that list by default. Git-Zen can connect to your instance and list your projects, but it still rejects webhooks from your instance. Tickets do not update from GitLab events until a later release fixes this. Before you link projects, contact support with your instance’s outbound IP address.

Step 1: Create a personal access token

1. Sign in to your GitLab instance as the Git-Zen user.
2. Open your avatar menu, then Edit profile → Access tokens.
3. Click Add new token.
4. Enter a name, such as “Git-Zen”.
5. Select the api scope.
6. Set an expiration date, or remove it if your instance allows that. When the token expires, Git-Zen stops working until you add a new token.
7. Click Create personal access token. Copy the token now. GitLab does not show it again.

Step 2: Install Git-Zen with the token

You do not need a GitLab.com account. A Zendesk administrator on the Enterprise plan can connect with the token directly.

1. Install Git-Zen for GitLab and authorize Zendesk. See Installing from Zendesk.
2. Click the Webhooks icon on the Git-Zen menu bar.
3. Find the text “Using a self-hosted GitLab instance?”. Click Use a Personal Access Token.
4. Paste your token into the Personal Access Token field, then click Save Changes.

This button shows only to Zendesk administrators on the Enterprise plan, and only while Git-Zen has no GitLab connection. If you already connected a GitLab.com account, use Switch to Personal Access Token in the GitLab OAuth User section instead.

Note

The setup wizard has a checkbox labeled “I am using a self-hosted GitLab instance”. Do not rely on it. Use the steps on this page to set your instance URL after installation.

Step 3: Enter your instance URL

After you save the token, the Webhooks screen shows a GitLab Instance URL field. The field appears only on the Enterprise plan, and only while you use a personal access token.

1. Enter the base URL of your instance, for example https://gitlab.mycompany.com.
   • Do not add /api/v4. Git-Zen adds it.
   • Leave the field blank to use gitlab.com.
2. Click Verify Connection. Git-Zen calls /api/v4/version on your instance with your saved token. On success, it shows Connected and your GitLab version.
3. Click Save Changes.
4. Refresh the Zendesk browser window.

Step 4: Link your projects

On the Webhooks screen, select your projects and click Save Changes. See Link GitLab projects with webhooks. The list now comes from your instance.

Verify Connection messages

Message	What to do
Self-hosted GitLab requires the Enterprise plan	Your account is not on Enterprise. Contact support.
URL and PAT are required	Enter the URL. Save a personal access token first.
URL must start with https://	Use an HTTPS URL. Git-Zen does not connect over plain HTTP.
Could not connect to GitLab instance	The server answered, but not with a GitLab version. Check that the URL is the root of your GitLab web UI.
Another error message	Git-Zen could not reach the server, or the token was rejected. Check the firewall rule for 52.202.91.72 and the token’s api scope.

Troubleshooting

Projects load, but tickets never update. Your instance’s webhooks do not reach Git-Zen. Check the project’s webhook in GitLab under Settings → Webhooks. Look at Recent events. A 403 response means Git-Zen rejected the source IP. Contact support. Also check that your instance allows outbound requests to api.git-zen.com.

I can see some projects but not others. See Group authorization.

I switched back to OAuth. OAuth connects to GitLab.com only. With OAuth, Git-Zen cannot reach your instance.

Need help?

Contact support. Include your GitLab instance URL, the project name, and the exact error message.