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 (sodependabot[bot]is matched literally).
GitHub and GitLab
| GitHub | GitLab | |
|---|---|---|
| Where the verdict comes from | The commit list of the pull request carries each commit's verification | Merge Pilot asks GitLab for the signature of each commit, one call per commit |
| Limit | GitHub lists at most 250 commits of a pull request. With 250 or more, the signatures cannot all be checked and the control fails | At most 100 commits are asked one by one. With more, the control fails |
| A failed read | Not applicable: the verdicts come with the commit list | When 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 value | What it does |
|---|---|---|
| Off | off | Signatures are not read. This is the default of a new policy |
| Report | report | Signatures are read and the result is shown; it never holds the merge |
| Enforce | block | The 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 |
| Result | Shown as | In Enforce mode | In Report mode |
|---|---|---|---|
| Not read yet for the head commit | Checking the commits' signatures. | The gate waits | Shown, does not hold |
| Every commit verified (or exempt) | All N commit(s) have verified signatures. | Passes | Passes |
| Commits without a verified signature | N commit(s) without a verified signature: … (the first five as sha (author), then and N more) | The gate is blocked | Shown as a warning |
| The signatures could not be checked | The commit signatures could not be checked: … | The gate is blocked | Shown as a warning |
| A watched repository whose company runs no scans on watched merge requests | Not scanned: scans are off for watched repositories. | Skipped | Skipped |
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 does | Default | Allowed values | Set where | Who can change it | API field |
|---|---|---|---|---|---|---|
| Signed commits | The control's mode | Off | Off, Report, Enforce | Policy | Policy managers, company admins, platform admins | controls.signatures.mode (off, report, block) |
| Authors that need not sign | Company 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 policy | Company setting | VCS logins, e-mails or names, separated by commas; * wildcards. An empty list of the policy's own exempts nobody | Policy override | Policy managers, company admins, platform admins | controls.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 does | Default | Allowed values | Set where | Who can change it | API field |
|---|---|---|---|---|---|---|
| Authors that need not sign | Commit authors whose unsigned commits are counted as exempt, not as findings, for every policy that does not set its own list | Empty: nobody is exempt | VCS login, e-mail or name, one per line; * wildcards | Company default | Company admins, platform admins | scanning.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
| Where | Field | Meaning |
|---|---|---|
| Policy | controls.signatures.mode | off, report or block |
| Policy | controls.signatures.overrides.exempt_authors | The policy's own exempt authors; absent: the company's |
| Company | scanning.signatures.exempt_authors | The company's exempt authors |
| Merge request | signatures.head_sha | The head commit whose commits were read |
| Merge request | signatures.checked | How many commits were read |
| Merge request | signatures.unsigned[] | Every commit without a verified signature, exempt authors' included: sha, name, email, username, reason (the VCS's verdict) |
| Merge request | signatures.error | Why the signatures could not be checked |
| Merge request | decision.controls[] with control: "signatures" | The control's status, blocking and reason |
Related pages
Video tutorial
Short videos of this feature working on real GitLab and Jira projects. English audio, English and Turkish subtitles. All video tutorials →