- Connect the project’s repository through the Earnie GitHub App or a GitLab token. See Connecting a repository.
- Attach at least one policy to the project. Without a policy, the gate has nothing to check, and the check reads No policies apply.
What Earnie Posts on a Pull Request
Each completed pull-request scan produces up to three things:
On GitHub, a push to the repository’s default branch also gets the
Earnie check, on the pushed commit. It has no comment, because there’s no pull request to comment on. GitLab doesn’t get a status for these pushes.
How the Check Is Decided
The findings the pull request introduced decide the check. Findings the default branch already had are listed in the summary comment, but they don’t hold the pull request. To tell which findings are new, Earnie compares the pull request with its latest completed scan of the default branch. The check shows one of these results:
While the scan runs, the check reads Earnie is scanning this change. A neutral check is never a pass: Earnie hasn’t found anything wrong, and it hasn’t cleared anything either.
When the Check Can Block a Merge
Earnie’s check stops a merge only where the provider enforces it. Everywhere else the connection is advisory: Earnie still posts its check and comments, and for a block or a needed approval, the summary comment and the scan page say Earnie recommends blocking. This connection cannot enforce it.On GitLab, a commit status doesn’t block a merge on its own. GitLab blocks on an outside
result only through external status checks, which need GitLab Ultimate. On Ultimate, set
Report the result as to Status check and turn on Status checks must succeed in the
GitLab project. See Reporting to GitLab as a status
check and Merge blocking depends on your GitLab
plan.
Making the Check Block a Merge on GitHub
Publishing theEarnie check doesn’t stop a merge on its own: GitHub has to wait for it. Add Earnie as a required status check, in a branch ruleset or in branch protection, on the branch your pull requests merge into.
Earnie reads that setting for each repository, using only the permissions the app already has:
- Where the
Earniecheck is required, a blocking gate stops the merge. - Everywhere else, the gate is a recommendation.
- If Earnie can’t read the setting, for example because GitHub hides a classic branch protection rule from the app, Earnie treats the gate as advisory.
Inline Comments on the Changed Lines
Earnie places an inline comment for a finding only when all of these are true:- No approval covers it.
- It’s new, and Earnie can attribute it to this pull request.
- It meets the project’s inline comment floor, or a policy flagged it.
- It overlaps a line the pull request added. A component finding from a manifest, which has no line of its own, goes on the first added block of that manifest.
- Earnie has a suggested fix for it.
When a Finding Is Resolved
- If a later push removes the finding, Earnie replies with the commit that resolved it, and resolves the thread. A thread belongs to its line, not to one finding, so Earnie resolves it only once no finding remains on that line.
- If a person resolves the thread while the finding still exists, Earnie treats that as an acknowledgement for this pull request, and doesn’t reopen it.
- If a finding returns after Earnie resolved its thread, it can get a new comment.
The Summary Comment
By default, Earnie posts the summary comment whatever the verdict, so a clean pull request also has a record of what Earnie checked. You can set a project to comment only when the gate fails, meaning it blocks, needs an approval, or failed to evaluate. A pull request or merge request that never failed then gets no summary comment. If it already has one, Earnie updates it when it passes, so a failing verdict doesn’t stay up after the fix. This works the same on GitHub and GitLab. Earnie doesn’t post a summary comment while the scan is running, for a cancelled scan, or when the check reads Base branch moved or No baseline.When the Check Is Neutral
Earnie needs a comparison with the default branch to tell which findings a pull request introduced. When it can’t make that comparison, the check turns neutral instead of guessing. No baseline to compare against. Earnie has no completed scan of the default branch, so it can’t tell which findings are new. Scan the default branch, then push a commit or re-run the pull request’s scan. Base branch moved. Someone merged or pushed to the default branch, so the pull request’s result may no longer describe what merging would produce:- Earnie scans the new head of the default branch.
- When that scan finishes, the check on every open pull request still based on the old head turns neutral, with the text Base branch moved; result is not conclusive.
- Push a commit or re-run the scan, and the check gives a real result again.
GitLab has no neutral status. On a merge request, a neutral check shows as success, with
the same text as its description, so it blocks nothing. Push a commit or re-run the scan to get a
real result back.
Choosing Which Pull Requests Earnie Checks
On a busy repository, not every pull request needs a check. An Operator or Admin can choose which pull requests Earnie scans, and how much it writes, in the project’s Scan Configuration, under Pull-request feedback. On a GitLab project the section is called Merge-request feedback.
Patterns accept exact names,
*, ?, [], and **, as in release/** or src/**.
None of these controls changes a verdict. They decide which pull requests Earnie scans and how much it writes. Earnie judges every pull request it scans against the same policies, and no setting here can turn a block into a pass.
When a Scan Fails
Sometimes a scan ends without a verdict: the scan itself failed, or a policy couldn’t be evaluated because the evidence it reads is missing. The check then reads Evaluation failed. When a scan fails decides what that check does:- Block, the default, publishes Evaluation failed as a failure. The pull request waits until a scan succeeds.
- Advisory publishes it as neutral instead, titled Evaluation failed (advisory, not blocking), which blocks nothing. Its summary adds This does not block the merge. Open Earnie to retry the scan.
On GitLab, an advisory check shows as success. GitLab has no neutral status, so Earnie closes
its commit status as success, and the description reads Evaluation failed (advisory, not
blocking). The merge request stays mergeable under Pipelines must succeed, even when
Earnie’s status is the pipeline’s only job.
Reporting to GitLab as a Status Check
On GitLab Ultimate, Earnie can report a merge request’s result as an external status check, which GitLab shows in the merge request’s Status checks widget. Report the result as decides where the result goes:- Commit status, the default, is a status on the head commit’s pipeline.
- Status check answers Earnie’s external status check instead.
- Both posts the two.
Earnie on the GitLab project. It deletes the check when you go back to Commit status or disconnect the repository. A push to the default branch is not affected.
Earnie posts nothing while the scan runs, so GitLab shows the check as pending, and GitLab fails a pending check that hears nothing within two minutes. The status check carries no text: the details stay in the summary note and behind the link to Earnie.
A status check needs GitLab Ultimate. On a connection without Ultimate, Earnie posts the
commit status whichever you choose, and the control says so. To make the status check block a
merge, turn on Status checks must succeed in the GitLab project’s merge request settings.
A skipped pull request has no check. Earnie doesn’t scan it, so it posts no check and no
comment. If you’ve made the
Earnie check a required status check, a pull request that Earnie
skips never receives it and can’t merge. Keep that in mind when you skip drafts or bots, or
narrow the base-branch and path lists.Setting the Controls for the Whole Organisation
The same eight controls are available for every project at Settings → Scan defaults, under Pull-request feedback. Turn on Apply to every project, the first control in that section, to make every project use the organisation’s values. Admins and Operators can change these controls and the lock. While the lock is on:- Each project’s section is read-only, shows the organisation’s values, and says that your organisation has locked these controls.
- Earnie keeps each project’s own saved choices. They take effect again when the lock is turned off.
Three Routes When a Policy Blocks a Merge
When a policy blocks a pull request, someone has to make a decision, and Earnie records it. The summary comment and inline comments show the finding, the rule that fired, and the evidence. You have three routes, and each one leaves a record of who decided and why:Route 1: Fix It
Upgrade or replace the component, and push the change. The next scan re-evaluates the pull request, and the gate clears without further action.Route 2: Correct the Finding
A finding can be wrong. For example, your own code matched a published copy of it, or Earnie identified the wrong package. In that case, triage it. For example, marking a finding as original removes it from the gate, because the policy doesn’t apply to it.Route 3: Request an Approval
When the risk is real, understood, and accepted, request a Policy Approval. It’s a recorded decision that one finding may pass one policy despite it. Admins and Operators can request one.- Open the finding from the summary comment, in Review, or in the violations table on the policy’s page.
- Select Request approval.
- Fill in the fields:
- Justification category says why the finding doesn’t apply or is acceptable: Component not present, Vulnerable code not present, Vulnerable code not in execute path, Vulnerable code cannot be controlled by adversary, Inline mitigations exist, Fixed, Under investigation, Incorrect data, or Other.
- Justification is your reasoning, in your own words.
- Expiry is 30 days (the default), 90 days, Custom date, or No expiry (not recommended).
- Select Request approval to submit.
What Happens Next
- The request is pending. The finding shows Pending approval. A pending request doesn’t change the verdict.
- An Admin decides. Only an Admin can approve or reject a request. They select Review request, which opens a drawer with the finding, the policy, who asked and when, the justification and the expiry. They select Approve or Reject, and must give a reason.
- Only an approval clears the finding. The gate holds it until then.
Give a request an expiry. Nobody revisits an approval that never expires. The policy pages
mark an approval as Expiring soon in its last seven days, so you can review it before it
lapses.
What an Approval Covers
An approval covers one finding against one policy, in one project. It carries forward to later scans and pull requests where the same finding meets the same policy, until it expires or is revoked. It doesn’t cover the same finding under another policy, or other findings of the same component. An approval requested for a finding that so far exists only in a pull request carries over to the project’s own finding once the change merges, with the same state and expiry.How an Approval Updates the Pull Request
When an approval changes a gate, Earnie updates theEarnie check and the comments of every scan it affects, straight away. The decision shows up on the pull request without anyone pushing a commit.
Earnie doesn’t re-scan or re-evaluate anything. The scan, its findings, and the policy revisions it was judged against stay the same. Only the approval is new, and the check now reflects it.
The check turns green only if approvals cover every violation still holding the gate. If another violation has no approval, the check stays red.
Revoking an approval updates the pull request the same way, in reverse.
Finding What’s Waiting on You
An Admin can find pending requests without opening each policy. The project’s Policies page has an Approvals tab next to All policies. Its count shows only the requests still awaiting a decision, across every policy attached to the project, so it reads zero once the queue is clear.- Decide a pending request with Review request on its row, which opens the same drawer.
- Switch Status between Pending, Approved, Rejected, and Revoked. Each option shows how many requests it holds. Expired approvals are listed under Approved.
- To withdraw an approval, find it under Approved and select Revoke. You can revoke only an approval that hasn’t expired.

- Its count is the pending requests of all the projects you can open.
- The queue has the same status buttons as a project’s, Pending by default. Each row adds the Project and the policy the request is on.
- Select a row, or Review request, to open the decision drawer. You can approve or reject only if you have approval permission on that request’s project. Without it, you see the request and no decision buttons.
- A request already decided opens read-only, with who decided it and why. Revoke ends an approval still in force.
- Require a different approver is under Approval rule, above the queue. Anyone can read it. Changing it needs organisation write permission.