Skip to main content
Video tutorial · 1:08

Signed commits

The Signed commits control requires every commit of a merge request to carry a signature that the VCS itself verified (GPG, SSH or X.509), so a commit cannot claim to come from someone who did not make it. Bots and service accounts that cannot sign can be exempted.

Merge Pilot does not verify signatures itself: it reads the verdict GitHub or GitLab gives for each commit. A commit counts as signed only when the VCS reports it as verified; an unsigned commit, a signature by an unknown key and a bad signature all count as not signed.

What it checks​

  • The merge request's commits, as the VCS lists them for the head commit.
  • For each commit without a verified signature, the commit's author is compared with Authors that need not sign: the author's VCS login, e-mail or name. A match makes the commit exempt: it is counted, not reported as a finding.
  • Patterns are compared ignoring case; * is the only wildcard (so dependabot[bot] is matched literally).

GitHub and GitLab​

GitHubGitLab
Where the verdict comes fromThe commit list of the pull request carries each commit's verificationMerge Pilot asks GitLab for the signature of each commit, one call per commit
LimitGitHub lists at most 250 commits of a pull request. With 250 or more, the signatures cannot all be checked and the control failsAt most 100 commits are asked one by one. With more, the control fails
A failed readNot applicable: the verdicts come with the commit listWhen reading one commit's signature fails, the control fails with the error

A list that may be incomplete never passes: the control fails with The commit signatures could not be checked: …

Modes​

The mode is set in the policy editor, Checks tab, row Signed commits.

Mode (label in the UI)API valueWhat it does
OffoffSignatures are not read. This is the default of a new policy
ReportreportSignatures are read and the result is shown; it never holds the merge
EnforceblockThe merge gate waits until the signatures are read, and is blocked while a commit lacks a verified signature or the signatures could not be checked
ResultShown asIn Enforce modeIn Report mode
Not read yet for the head commitChecking the commits' signatures.The gate waitsShown, does not hold
Every commit verified (or exempt)All N commit(s) have verified signatures.PassesPasses
Commits without a verified signatureN commit(s) without a verified signature: … (the first five as sha (author), then and N more)The gate is blockedShown as a warning
The signatures could not be checkedThe commit signatures could not be checked: …The gate is blockedShown as a warning
A watched repository whose company runs no scans on watched merge requestsNot scanned: scans are off for watched repositories.SkippedSkipped

When exempt authors' commits were left out, the result adds N commit(s) of exempt authors not checked.

See Controls for how modes combine into the merge gate.

Settings​

In the policy​

Shown when the mode is Report or Enforce.

Setting (label in the UI)What it doesDefaultAllowed valuesSet whereWho can change itAPI field
Signed commitsThe control's modeOffOff, Report, EnforcePolicyPolicy managers, company admins, platform adminscontrols.signatures.mode (off, report, block)
Authors that need not signCompany setting (…) uses the company's list, shown in brackets (none when it is empty). This policy's list replaces it for this policy, with the list typed in Authors that need not sign for this policyCompany settingVCS logins, e-mails or names, separated by commas; * wildcards. An empty list of the policy's own exempts nobodyPolicy overridePolicy managers, company admins, platform adminscontrols.signatures.overrides.exempt_authors (absent or null: the company's list; []: nobody)

Company default​

On the company page, Scanning tab, section Commits, card Signed commits.

Setting (label in the UI)What it doesDefaultAllowed valuesSet whereWho can change itAPI field
Authors that need not signCommit authors whose unsigned commits are counted as exempt, not as findings, for every policy that does not set its own listEmpty: nobody is exemptVCS login, e-mail or name, one per line; * wildcardsCompany defaultCompany admins, platform adminsscanning.signatures.exempt_authors

The company settings are saved with Save changes on the company page (PUT /api/v1/companies/{id} with the scanning object).

When it runs​

  • The signatures are read while Merge Pilot processes the merge request for a new head commit, when its policy has the control in Report or Enforce. There is no separate job and no Re-scan button.
  • They are read once per head commit. A read that ended with an error is tried again the next time the merge request is processed.
  • When the commit list itself could not be read, the control stays at Checking the commits' signatures. until the merge request is processed again.
  • Signatures are not read for the past merge requests imported when a repository is first watched.
  • On watched repositories they are read only when the company scans watched merge requests (Company → Repositories, Scan watched merge requests for secrets, vulnerable dependencies and licenses; the signature check counts as a scan).

What the merge request shows​

  • Policy card: the Signed commits line of the decision checklist, with the result described above. In Report mode a failure is marked (report only).
  • My Work: a merge request held by this control is listed with the reason Unsigned commits.
  • The merge gate's check and the status comment on the merge request list the control with the other controls.

Exceptions​

There is no exception for one commit or one merge request. Exempt the author (for the company or for one policy), or set the control to Report in the policy that covers such changes. A commit made without a signature stays in the merge request's history: rewriting the branch with signed commits gives a new head commit that is checked again.

Audit log​

The control has no audit action of its own. Its effect on the merge gate is recorded by the merge request evaluation actions (mr_gate_blocked, mr_gate_pending, mr_gate_approved); see Audit log.

API fields​

WhereFieldMeaning
Policycontrols.signatures.modeoff, report or block
Policycontrols.signatures.overrides.exempt_authorsThe policy's own exempt authors; absent: the company's
Companyscanning.signatures.exempt_authorsThe company's exempt authors
Merge requestsignatures.head_shaThe head commit whose commits were read
Merge requestsignatures.checkedHow many commits were read
Merge requestsignatures.unsigned[]Every commit without a verified signature, exempt authors' included: sha, name, email, username, reason (the VCS's verdict)
Merge requestsignatures.errorWhy the signatures could not be checked
Merge requestdecision.controls[] with control: "signatures"The control's status, blocking and reason
  • Controls: every control and how modes work.
  • GitHub and GitLab: the connections whose verdicts are read.

Video tutorial

Short videos of this feature working on real GitLab and Jira projects. English audio, English and Turkish subtitles. All video tutorials →

Require Signed CommitsYouTube ↗