Using self-managed GitLab on your phone: VPNs, certificates and tokens

Most GitLab app reviews assume gitlab.com. But a large share of GitLab users work on their company’s own instance — on a private network, behind single sign-on, with a certificate from an internal authority. All of that affects a phone. Here is what has to be true for it to work, in the order things usually go wrong.

1. Can the phone reach your GitLab?

Open your instance’s address in the phone’s browser first.

• It loads on mobile data: the instance is on the internet. Any app can reach it.
• It loads only on office Wi-Fi or the VPN: the instance is internal. Apps work while the phone is on the VPN, and stop when it is not.
• It does not load at all: ask IT whether phones are allowed on the VPN, or whether the instance is reachable through a gateway.

Single sign-on (SAML or OIDC) is usually not a problem for personal access tokens: you create the token in the browser while signed in, and the app uses the token, not your SSO login. Some organisations restrict personal access tokens; if creating one is blocked, ask your administrator.

2. Does the phone trust the certificate?

If the browser shows a certificate warning, an app will refuse to connect — and a good app will not offer to ignore it, because a “trust anyway” button would expose your token to anyone on the network.

• iPhone: install your company’s root certificate as a profile (IT usually provides one), then turn on full trust for it under Settings › General › About › Certificate Trust Settings. Apple’s support article walks through it.
• Android: since Android 7, apps no longer trust certificate authorities that you or an administrator add to the phone, unless each app explicitly opts in. In practice, a self-managed instance should use a certificate from a public authority (such as Let’s Encrypt) for third-party apps to connect.

3. Sign in with a personal access token

On self-managed GitLab, most apps sign in with a personal access token:

1. In your instance, open User settings › Access tokens and create a token.
2. Pick the scope the app needs: api for an app that approves, merges or comments; read_api for one that only reads. (What each scope allows.)
3. Set an expiry date — 365 days at most by default — and paste the token into the app.

Two administrator settings can change this: on Ultimate, admins can cap token lifetimes below 365 days, and since GitLab 19.2 an instance can require fine-grained tokens. If tokens you create stop working early, or classic tokens are refused, ask your administrator which applies.

4. Is your GitLab version supported?

Apps rely on newer API fields as GitLab adds them, so each has a minimum version: MergeBell supports GitLab 16.0 and later, GLab lists 14.x and later, and Control for GitLab lists 9.x and later. Your administrator can tell you the exact version. Instances more than a couple of years old usually get a “not supported” message rather than strange errors.

5. How do push alerts work for a self-managed instance?

Push needs something that checks GitLab while your phone sleeps. That is a server on the internet, so:

• If the instance is reachable from the internet, server-side alerts work as they do for gitlab.com. MergeBell’s alert server uses a separate read-only key, from relay.mergebell.app, and your administrator can allow-list it.
• If the instance is only on a private network, no outside server can reach it. MergeBell then switches that instance to checks on the phone, labelled as such: the app looks for new to-dos when the phone’s system lets it run in the background, so alerts can arrive later than server-side ones.
• Instant alerts use a project webhook that calls the alert server, so they need the instance to be able to reach the internet, and the Maintainer role to set up.

For GitLab administrators

If your security team is evaluating a GitLab app, ask for three things in writing: where the sign-in token is stored, what any server receives, and which GitLab endpoints that server calls. MergeBell’s answers are on its security page: the token stays on the phone, the alert server holds only a read_api key and refuses anything more, and it reads GitLab through eight listed GET endpoints from one host name.