- GitHub, through a GitHub App that Earnie creates and your organisation installs.
- GitLab, through an access token that you paste into Earnie.
Before You Begin
In Earnie, you need the Admin role. Only an Admin can connect, change, or disconnect a GitHub or GitLab connection, or import all its repositories at once. An Operator can see the connections and add repositories from an existing connection as projects. See Team & roles. On GitHub, you need to be an owner of the GitHub organisation that holds the repositories. If you aren’t, you can start the connection and send a link to an owner to finish it. See If You Are Not an Organisation Owner. On GitLab, you need an access token for the group or project that holds the repositories, and that token needs the Maintainer role on the projects you want to scan. See Choosing a GitLab Token. If you host Earnie yourself, your Git server must be able to reach Earnie’s public address, because it sends Earnie an event each time code changes. Connecting github.com also needs a GitHub sign-in setting on your installation. See GitHub.com in Installing Earnie.Connecting GitHub
Earnie reads your GitHub repositories through a GitHub App: an integration that a GitHub organisation installs to give a service limited access to chosen repositories. Earnie creates the app for you, owned by your organisation, and you then install it.What Earnie Asks For
Earnie’s access to your source code is read-only, and covers only the repositories you choose when you install the app. It can also write to pull requests and checks, so it reports its results where your team reviews code.
The app receives two kinds of event from GitHub: pushes and pull request activity. Earnie uses them to start scans. See What Triggers a Scan.
Connect GitHub

- In Settings, on the Integrations tab, select Connect GitHub on the GitHub App card.
- Authorise Earnie to see your organisations. Select Authorize on GitHub, copy the code Earnie shows, select Open GitHub, and enter the code there. This lets Earnie list the GitHub organisations you belong to. It doesn’t grant access to any code.
- Choose where to install. Pick the organisation that owns the repositories you want to scan. The list shows whether you’re an owner or a member of each one, and also offers your personal account.
- Create the app. Select Create app for your organisation. Earnie creates the Earnie app, owned by that organisation, with the permissions above.
- Install the app. Select Install on GitHub. On GitHub, choose all repositories or only the ones Earnie may read, then select Install.
If You Are Not an Organisation Owner
Only an owner of the GitHub organisation can create and install the app. If you choose an organisation where you’re a member, Earnie gives you a single-use hand-off link instead of step 4. Send it to an owner of that organisation. The owner opens the link, and creates and installs the app on GitHub. They don’t need an Earnie account. Your Earnie window finishes the connection on its own once they’re done. The link expires after seven days and shows its expiry date. If it has expired or was already used, start the connection again to get a new one.Connecting GitHub Enterprise Server
You can also connect your own GitHub Enterprise Server. You do this from Settings, not from the setup wizard.- On the GitHub App card, select Connect GitHub, or Connect another GitHub if a GitHub connection already exists.
- Choose GitHub Enterprise Server instead of github.com.
- Enter the server’s Address, such as
https://github.example.com. A server that serves only plain http connects only if your Earnie operator allowed it; see Connecting a Plain http Host. - If an internal certificate authority (CA) signed the server’s certificate, paste that CA certificate into CA certificate. Earnie trusts it for this server only.
- Type the organisation that will own the app, or leave it empty for your personal account. There is no authorisation code for Enterprise Server.
- Create and install the app, as for github.com.
Connecting GitLab
Earnie connects to GitLab with an access token instead of an installed app. Earnie can reach whatever the token can reach, so the kind of token you choose decides which projects Earnie sees.Choosing a GitLab Token
The token must meet three requirements:- Its GitLab host runs GitLab 17.4 or later. The host can be gitlab.com, GitLab Dedicated, or a self-managed instance.
- It has the
apiandread_repositoryscopes. Earnie needsapito register a webhook on each project and to post its results on merge requests. - It is active and unexpired.
To scan a project, the token also needs the Maintainer role on it, because Earnie registers a webhook on each project you add. Earnie refuses to add a project where the token has less, and creates nothing.
Earnie checks a token’s scopes, so use a group, project, service account, or
classic personal access token. A fine-grained personal access token, which
carries per-resource permissions instead of scopes, may not pass the check.
Connect GitLab

- In Settings, on the Integrations tab, select Connect GitLab on the GitLab card.
- Enter the Host. The default is
https://gitlab.com. For a self-managed or Dedicated instance, enter its address, starting withhttps://. Anhttp://address works only if your Earnie operator allowed that host; see Connecting a Plain http Host. - Paste the Access token. Earnie never shows it again.
- If an internal certificate authority signed your GitLab’s certificate, select My GitLab uses an internal CA and paste the CA certificate. See Trusting a Private CA.
- Select Check token. Earnie checks the host and the token with GitLab, then shows the token’s account, kind, scopes, expiry, and merge-blocking mode.
- Select Connect.
Having a Group Owner Connect It
If you can’t create the token yourself, a GitLab group Owner can connect GitLab for you, without an Earnie account:- On the GitLab card, select Send link to a group Owner.
- Enter the Host, and optionally the Group, which tells the Owner which group to connect.
- Select Create link, then Copy link, and send it to the Owner.
api and read_repository scopes, and pastes it there. Earnie connects GitLab for your organisation. The link works once and expires after seven days.
Trusting a Private CA
If your company’s own internal certificate authority signs your self-managed GitLab’s certificate, Earnie can’t verify the host until you give it that CA. Earnie doesn’t trust your internal CA by default. Paste the CA certificate, in PEM format, into My GitLab uses an internal CA on the connect form, or upload it as a file. Earnie trusts it for this connection only. If you select Check token without it and the certificate fails to verify, the form opens the field for you. The GitLab card then shows the certificate’s name and expiry. When the certificate is renewed, select Replace CA certificate.Connecting a Plain http Host
Earnie sends your access token with every call to GitLab or GitHub Enterprise Server and every clone, so by default it connects only over https. If you run Earnie yourself and your GitLab or GitHub Enterprise Server serves only plain http on a network you control, the person who operates your Earnie installation can allow that host. They add the host toEARNIE_SCM_INSECURE_HTTP_HOSTS in tenant.env and restart Earnie. The value is a comma-separated list of host or host:port, such as gitlab.intra,ghes.corp:8080. The port is part of the entry, and the setting is empty by default.
- A listed host is connected over http, whether you type
http://orhttps://. Every other host still needs https. - The setting applies when you connect. A connection keeps the address it was saved with, so after a host is added or removed, disconnect and connect it again. For GitHub Enterprise Server, create the app again.
- The card shows Unencrypted on a connection that uses plain http.
Adding Repositories as Projects
Each repository you want to govern becomes an Earnie project. To add one:- On any project’s page, select New scan, then the Repository tab. In the setup wizard, the Select repository step shows the same list.
- If you have more than one connection, choose one in the selector above the list, for example GitLab · acme.
- Pick the repository. Earnie lists the repositories the connection can reach, grouped by organisation or GitLab namespace, such as
acme/platform/infra. Archived repositories are left out. - Select Start scan. Earnie creates a project for the repository, connects it, and runs its first full scan.
acme/api on gitlab.com and on your own GitLab, gives two separate projects. Each one scans through the connection you picked it from.
If a repository is missing from the list, the connection can’t reach it. On GitHub, grant the Earnie app access to it with Manage repositories. On GitLab, give the token access to its group or project.
Importing All Repositories at Once
To govern every repository from day one, import all of a connection’s repositories in one go, instead of adding them one at a time. This needs the Admin role.- In Settings, on the Integrations tab, select Import all repositories on the GitHub App or GitLab card.
- Pick the connection, if there are several.
- Optionally, narrow the repositories by path.
*stands for anything, soacme/*takes one organisation or group,acme/platform/*takes one GitLab subgroup, and*-servicetakes every repository whose name ends in-service. To include forks, select Include forks. Earnie always leaves out archived repositories, since they receive no changes. - Select Preview. Earnie shows how many repositories it will import, and how many it leaves out because they’re already imported, don’t match the filter, are forks, or are archived. Nothing is created yet.
- Select Import, followed by the number of repositories, such as Import 42 repositories. Earnie creates one project per repository, connects it, and scans it once.
- A repository that fails shows the reason. For example, a GitLab token without the Maintainer role can’t add the webhook, or a self-managed GitLab refuses webhooks to a private address. See Troubleshooting. Fix the cause and select Retry failed. Earnie imports only the failed repositories again.
- Stop import skips the repositories not started yet. The projects already created stay.
- Importing again later adds only the repositories that aren’t imported yet.
What Happens After a Repository Is Connected
What Triggers a Scan
Once a repository is a project, Earnie scans it in two cases, on GitHub and on GitLab:- Opening or updating a pull or merge request starts a scan of the change. It is a partial-coverage scan, which checks what the change introduces. Updating means pushing new commits, changing the target branch, reopening it, or marking a draft as ready.
- A push to the default branch starts a full scan of the repository, which updates the project’s findings.
Feedback on a Pull or Merge Request
On GitHub, Earnie posts a check namedEarnie, a summary comment, and inline comments on the changed lines. Merge gate describes each one. The check blocks a merge only on a branch where Earnie is a required status check. See Making the Check Block a Merge on GitHub.
A GitLab merge request gets the same three things, under GitLab’s names for them:
Merge Blocking Depends on Your GitLab Plan
A commit status doesn’t block a merge by itself. GitLab blocks a merge on an outside result only through external status checks, which need GitLab Ultimate. On Ultimate, Earnie can report its result as an external status check: set Report the result as to Status check in the project’s Merge-request feedback, and turn on Status checks must succeed in the GitLab project. See Reporting to GitLab as a status check. Without Ultimate, Earnie’s verdict is advisory: it doesn’t stop a merge. When the verdict is Block or Needs approval, the summary note says that Earnie recommends blocking but this connection can’t enforce it. The Merge blocking row on the connection shows Advisory, or Enforced when the token can see that the group’s plan is Ultimate. GitLab shows a group’s plan only to a token with the Owner role.Managing the Connection

Managing GitHub
Disconnecting GitHub
Disconnecting a host uninstalls the Earnie app from your organisations on that host and deletes its stored credentials. Earnie can no longer read your repositories, and their scans stop. Your projects stay, with their findings and decisions, but are no longer connected to a repository. The app itself stays registered on GitHub, in the developer settings of the organisation that owns it. Delete it there if you don’t plan to reconnect.Managing GitLab
The GitLab card shows each connection’s health, scopes, account, token kind, and token expiry. The expiry turns amber 14 days before the token expires, and red 3 days before.
To renew a token, create a new one for the same group or project, with the same scopes, and paste it into Replace token. Earnie keeps the connection and its webhooks. Then revoke the old token on GitLab.
Below the connections, Repositories previews the GitLab projects your tokens reach. View all lists every one with its language, visibility, and default branch, and lets you filter them. The list shows what Earnie can read, not what you’ve added as projects.
Disconnecting GitLab
Disconnecting removes the webhooks the connection registered on GitLab and deletes its stored token. Its projects keep their scans and history, but stop scanning and show as not connected. Revoke the token on GitLab too. If you connect the same group or project again later, those projects get their connection back, and Earnie registers their webhooks again.Connection Health
Earnie checks regularly, every 15 minutes by default, that each connection still has the access it needs, and shows the result on its card on the Integrations tab. A provider that doesn’t answer for a while never changes the state. Only a lasting problem does.GitHub Connection Health
Earnie also checks a GitHub connection right after you connect it or change its permissions.Fixing a Missing Permission
When a permission is missing, the card lists it and offers Review on GitHub. Select it, then accept the new permission request on the app’s installation page. The state returns to Healthy on the next check.When the App Is Removed on GitHub
If someone uninstalls the app on GitHub, the card shows Disconnected. The next time Earnie compares its connections with GitHub, every 15 minutes by default, it removes that connection. To restore access, install the app again from Earnie, with Add organization. Earnie keeps only installations started from Earnie. If someone installs the app directly on GitHub, Earnie removes that installation the next time it compares its connections with GitHub.The state also shows on projects. A project whose repository belongs to an
affected connection shows a GitHub connection degraded or GitHub
connection disconnected badge in its header, which links to the
Integrations tab. Earnie records every change of state in the
organisation audit log as
Integrations connection health changed.
GitLab Connection Health
Earnie re-checks each GitLab connection’s token and webhooks:
An expired or revoked token reads “GitLab no longer accepts this token”. Replace it with Replace token.
GitLab disables a webhook for good after many failed deliveries in a row. Earnie notices this and tries to turn the webhook back on with a test delivery. If that fails, or the webhook was deleted, the connection is Degraded, and the card says that GitLab stopped sending a project’s events. To fix it, disconnect that project from its repository and connect it again, which registers a new webhook.