We started Ellipsis (a developer tool that automatically reviews code and fixes bugs) as a GitHub App, and by popular demand recently started supporting GitLab. 

While third-party apps are ubiquitous in the GitHub ecosystem, GitLab offers an integration guide for third-party integrations, which can be found at developer.gitlab.com, which differs from GitHub’s application concept. Recognizing this unique approach, we’re sharing our experience adapting our GitHub Application to GitLab’s framework. Our goal is to provide a solution tutorial to inspire and assist other developers in bringing their innovative GitHub applications to the GitLab community, thus enriching both ecosystems.

Background Concepts

GitLab offers a unique approach to third-party integrations. While GitHub combines authentication, webhooks, and UI into its ‘Application’ concept, GitLab treats these as individual components, providing more granular control. This architectural difference allows developers to build custom integrations tailored to their needs.

The GitLab Applications API allows for access to GitLab resources and taking actions on behalf of a particular user, but we want to take actions on behalf of our bot account.

A Note on Nesting

GitHub has Accounts (Users or Organizations) and Repositories, but there’s only one level of nesting. In GitLab, Repositories are called Projects, but you can have an arbitrary amount of nesting through Groups!

Depending on how you structured your application logic, you might need to rethink some assumptions and rewire things, because instead of always having a path `owner/repo`, you can now have customers with `top_group/sub_group/another_sub_group/project_name`.

You might ask, “Well, how many groups, sub-groups and projects could one company possibly have?” It’s more than you expect, even if you take this advice into account.

SaaS vs. Self-Managed

Unlike GitHub, where the vast majority of users use the SaaS offering, GitLab offers both SaaS and self-managed deployment options for its open-core software. Self-managed enables users to have more control and helps meet security requirements. 

In addition to handling SaaS installations from users at https://gitlab.com, your application code will need to track the hosts/domain, which will often look something like https://gitlab.example.com.

Authentication with Access Tokens

End users will need to manually create an Access Token. There are two kinds: Group Access Tokens, Project Access Tokens. There’s no real difference besides what they refer to. (There are also Personal Access Tokens, but that’s not what we want, because that will impersonate the installing user instead of appearing as a bot.)

A Group Access Token grants privileges to all its subgroups and subprojects, which is extremely convenient for an org with hundreds of nested entities, which can just pick the top-level group. However, customers will often want to install an application in only a part of their org, so plan for that.

Your customer can create the token using the GitLab UI, and set a few fields specific to your application:

• Name: This is the display name for actions, comments, etc. will be attributed in the GitLab UI. Your customer can theoretically use anything they want.

• Role: Check the role docs to see what you need. We needed Developer, which makes sense, given we’re building an AI software developer.

• Scopes: Check the scope docs to see what you need. We needed api, read_repository, and write_repository.

• Expiry date: The maximum your customer can set it to is 1 year into the future. This is a tradeoff between how often the customer wants to update, and might depend on their internal policies. GitLab Ultimate admins may set the maximum access token expiry limit to less than 365 days, so consult with your end user’s GitLab admin team to determine the ideal expiry time frame.

The Bot User

GitLab automatically associates an access token with a Bot user. Although you can set the display name, GitLab does not allow you to set the picture or username (which will be auto-generated for you, e.g. `group_123_bot_4ffca233d8298ea1`). 

The custom name you picked will work for autocomplete purposes (it’ll expand to the full username as you type), which is actually a marked improvement over GitHub (which doesn’t allow autocomplete for bots/Apps).

Setup Webhooks

Next, we need Webhooks, which are managed separately from the Access Token. Your user will go to whichever top-level group or project they used to create their Access Token, and use the Webhook UI to create one, setting a few more fields specific to your application:

• URL: The URL where your web server will receive the POST requests from GitLab. Aside: You might find it helpful to use an event gateway like Hookdeck for better reliability and visibility.

• Events: It depends on your application; checkout the full list of Webhook Events. We needed: Push events, Issue events, Merge request events, and Comments.

• Secret token: For security, you’ll want to generate a unique cryptographically strong string for each customer, which they will enter into this field. Without this, somebody could spoof events. You’ll set up your application to verify this secret on incoming requests.

• SSL Verification: Make sure the checkbox for SSL verification is enabled!

OAuth and Logins

Strictly speaking, you do not need to setup OAuth/login with GitLab for users to get started with your app. You can use the Access Token directly to check access by checking if your GET requests succeed. If you’re using Python, the python-gitlab library can make this easier.

However, being able to “Login with GitLab” is likely convenient if you want users to be able to manage settings, billing, etc. The setup here is typical and similar to what you had to setup for “Login with GitHub” functionality - see the GitLab OAuth docs. Some third-party libraries can make this easier, such as the NextAuth.js GitLab provider.

Putting it all together

You’ll probably want a simple webpage with instructions, and a form for users to submit 1) the group/project URL, 2) the access token, and 3) the webhook secret (or you can auto-generate the secret and show it to your user for them to copy). 

You can explore our setup page here: https://app.ellipsis.dev/gitlab. We’ve designed it with simplicity and clarity in mind, focusing on providing a straightforward, effective solution to help you get started quickly on GitLab with Ellipsis.