Connect GitLab

To connect GitLab to Neo.Tax, you’ll create a bot user in your own GitLab with read-only access to the group you want Neo.Tax to analyze, and paste its access token into Neo.Tax. The token belongs to your organization, not to a person, and nobody signs in through a browser. It takes about five minutes.

This works for GitLab.com and for self-managed or Dedicated GitLab instances that are reachable from the internet.

You’ll need to be an Owner of the top-level group you want to connect (on self-managed instances, an administrator may need to do the first step). The steps below walk you through it.

After connecting, you can optionally upload a CSV mapping GitLab usernames to work emails, so the data from GitLab can be matched to payroll.

Before you start

• Decide which top-level group Neo.Tax should read. Neo.Tax reads every project in that group and all of its subgroups. One group per Neo.Tax account; if you need more than one, talk to your implementation team.
• GitLab 16.0 or later is required. GitLab 17.9 or later is recommended so Neo.Tax can renew the token for you automatically (see Token expiry and renewal below).
• Self-managed instances must be reachable from the internet over HTTPS with a certificate from a public certificate authority. Instances behind a firewall, or using an internal certificate authority, can’t be connected yet; use the file-upload path instead.

Part 1: Create the bot user and its token in GitLab

There are two kinds of bot user. Use a service account if you can. It survives group reorganizations and is the kind GitLab recommends for integrations. Use a group access token only if your instance can’t create service accounts.

Option A: Service account (recommended)

Service accounts are available on every GitLab tier, including Free, since GitLab 18.11. On GitLab.com, the group Owner may be asked to verify their identity the first time.

1. In GitLab, open your top-level group, then go to Settings → Service accounts and click Add service account. Give it a recognizable name, for example neo-tax-bot.
2. Add the service account to the group: go to Manage → Members → Invite members, search for the service account by name, and give it the Reporter role. Reporter is the lowest role that can read merge requests in private projects.
3. Back on Settings → Service accounts, open the service account’s menu (the ⋮ icon), choose Manage access tokens, and click Add new token.
4. Name the token (for example Neo.Tax), set an expiry date (GitLab requires one; 365 days is the default and the maximum), and select exactly two scopes: read_api and self_rotate. Do not select api or read_repository.
5. Click Create token and copy the token now. GitLab will not show it again.

Option B: Group access token

Use this on a self-managed instance running GitLab 18.10 or earlier, or where your administrator doesn’t allow group Owners to create service accounts. On GitLab.com, group access tokens require a Premium or Ultimate subscription.

1. In GitLab, open your top-level group, then go to Settings → Access tokens and click Add new token.
2. Name the token (for example Neo.Tax), set an expiry date, choose the Reporter role, and select exactly two scopes: read_api and self_rotate. Do not select api or read_repository.
3. Click Create token and copy the token now. GitLab will not show it again.

Part 2: Connect GitLab in Neo.Tax

1. Log in to app.neo.tax and go to Projects → Connect Project Management → GitLab.

2. Fill in three fields:

   1. GitLab URL: leave https://gitlab.com for GitLab.com, or enter your instance’s address (for example https://gitlab.example.com).
   2. Access token: paste the token from Part 1.
   3. Group: the path of your top-level group, as it appears in the group’s URL (for example acme for https://gitlab.com/acme).

3. Click Connect. Neo.Tax checks the token against your GitLab before saving anything, and then shows you what it connected to: the bot user it signed in as, the group, how many projects it can see, when the token expires, and whether Neo.Tax can renew it automatically.

If something is wrong, the check fails right away and tells you which of these it was:

Connecting doesn’t start a sync. Your implementation team will run the first sync with you.

Part 3: Mapping GitLab to payroll

Neo.Tax matches GitLab activity to people in your payroll data by email. It reads the email addresses on merge request commits automatically, which covers most people. For anyone it can’t match that way, upload a mapping of GitLab usernames to work emails:

1. Create a CSV with two columns: GitLab Username and Work email.
2. Go to Neo.Tax → Data Sources and select Upload GitLab Emails.

Token expiry and renewal

GitLab requires every access token to have an expiry date. If you created the token with the self_rotate scope (GitLab 17.9 or later), Neo.Tax renews it for you about a month before it expires, and you don’t need to do anything. If the renewal ever fails, the person who connected GitLab gets an email, and the connection shows Token rotation failed.

If the token can’t be renewed automatically, the connection shows Token expires on a date once it’s within thirty days. Before that date, create a new token in GitLab (Part 1, step 3 onward) and use Update credentials on the connection in Data Sources to paste it in. Your configuration and sync history are kept.

Disconnecting

On Data Sources, choose Disconnect on the GitLab connection. Neo.Tax revokes the token in GitLab and removes it from Neo.Tax. Everything already synced is kept.

Troubleshooting

Our self-managed GitLab uses an internal certificate authority. This isn’t supported yet. If your instance can present a certificate from a public authority (for example Let’s Encrypt), connect with that; otherwise use file upload.

We allowlist inbound IP addresses. Ask your implementation team for the address Neo.Tax connects from.

The connection worked, then stopped. The token was probably revoked or expired in GitLab. Create a new one and use Update credentials.

FAQ

Q: Does Neo.Tax look at my source code?

A: No. Neo.Tax never requests file contents, diffs, or repository trees from GitLab, and the token you create can’t clone repositories because it doesn’t have the read_repository scope. One thing to know: GitLab has no role that can read merge requests in private projects without also being allowed to read code, so the Reporter role you grant could technically read it. Neo.Tax doesn’t, and publishes the exact list of fields it reads below. If your security policy can’t accept that, use the file-upload path instead.

Q: Exactly what does Neo.Tax read from GitLab?

A: The list of projects in your group and subgroups; the group’s members (username, display name, public email); merge requests (title, description, author, assignees, reviewers, approvers, state, labels, milestone, dates, and their activity history); and for each merge request’s commits, the author name and email, dates, and commit title. Nothing else.

Q: How does Neo.Tax use GitLab data?

A: We use merge requests as the primary signal. Each merge request is treated as a task done by a specific person, and our AI groups them into projects. Each GitLab project is treated as a team.

Q: Do I need to use GitLab Issues?

A: No. The system works off merge requests. As long as your team uses merge requests, your data will work.

Q: How does this match to my cost data?

A: By email. Neo.Tax reads the email on each person’s commits automatically, and you can fill any gaps with the mapping upload in Part 3.

Q: Can I use both GitLab and JIRA with Neo.Tax**?**

A: Yes. This works best when different teams use different systems, for example engineering in GitLab and project management in JIRA. We usually recommend starting with your most widely used system first, then adding the second if there are coverage gaps. Your implementation team will help you decide.

Q: We have several top-level groups. Can we connect all of them?

A: One group per Neo.Tax account today. Connect the one that holds most of your engineering work, and talk to your implementation team about the rest.

Q: I have a single tenant set up. Does that change anything?

A: No. Unlike the GitHub App, there’s nothing Neo.Tax needs to create on its side. The steps are the same.