# Handle a push blocked by secret scanning

Remove a credential a push was refused for, or push past the check with a recorded reason.

While secret push protection is on for a repository (the default), every push, over HTTPS, SSH or
from the Deutsche Cloud Console, has the text files it adds checked for credentials with a recognisable format
(38 rules): AWS, Google, Azure storage, Hetzner Cloud and Deutsche Cloud keys and tokens; GitHub,
GitLab, Slack, Stripe, OpenAI, Anthropic, Hugging Face, SendGrid, npm and PyPI tokens; Slack,
Discord and Teams webhook URLs; private key blocks. There is no "high entropy" rule, so
random-looking strings do not block a push. A match refuses the push and names the file, the line
and the kind of secret:

```
remote: Push blocked by secret scanning: 1 secret found.
remote:
remote:   - AWS access key ID in config/prod.env:3 (AKIA…(20), blob 1f3a9c2e7d)
remote:
remote: Remove the secret from the commits (amend or rebase them; a later commit deleting
remote: the file is not enough, the history still has it) and revoke it if it was real.
remote: If it is a test value or a false positive, push again with a reason:
remote:   git push -o secret_scanning.bypass="<why this is safe>"
remote: A bypass needs git:BypassSecretProtection and is recorded as an alert.
```

The refused push is listed on the repository's **Secret scanning** page with the state
**Blocked**.

## Prerequisites

- To push past the check, `git:BypassSecretProtection` on the repository. A deploy key cannot hold
  it, so a deploy key can never push past the check.
- To see the alerts, `git:ListSecurityAlerts`; to close one, `git:UpdateSecurityAlert`.

## Remove the secret

Remove the secret from the commits (amend or rebase; a later commit that deletes the file is not
enough), revoke it if it was real, and push again.

A line that contains the marker `ews:allow-secret` (for example in a comment next to a test
fixture) is never reported. It works per line: for a private key block, put it on the
`-----BEGIN … PRIVATE KEY-----` line.

## Push with a reason

If the match is wrong or the value is a test fixture, push with a reason. The push goes through
and each secret is recorded as an alert in the state **Bypassed**, with who pushed it and the
reason:

```sh
git push -o secret_scanning.bypass="test fixture, not a real key" origin my-branch
```

An empty reason counts as no bypass. Without `git:BypassSecretProtection` the push is still
refused, and the message ends with `The bypass was refused: you lack git:BypassSecretProtection on
this repository.`

## Close the alert

Close a bypassed alert as revoked, false positive, used in tests or won't fix. A blocked alert has
nothing to close: its push never landed.

**Console**
1. In the repository, choose **Security**, then **Secret scanning**.
2. Open the alert's actions menu and choose **Close as revoked**, **Close as false positive**,
   **Close as used in tests** or **Close as won’t fix**. The alert's state becomes **Resolved**.

**CLI**
```sh
dcloud git security resolve-secret-alert 5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60 \
  f0e1d2c3-b4a5-4968-8776-655443322110 --resolution used_in_tests
```

**API**
```http
PATCH /git/api/repositories/5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60/security/secret-alerts/f0e1d2c3-b4a5-4968-8776-655443322110
{ "resolution": "used_in_tests", "comment": "Fixture key" }
```

`5d6c2a1e-…` is the repository id and `f0e1d2c3-…` the alert's id
(`dcloud git security list-secret-alerts`). An id that is not a bypassed alert of the repository
answers 404 `No bypassed alert with that id (a blocked push never landed)`.

## Result

The secret itself is never stored, only a redacted preview (`AKIA…(20)`) and a fingerprint. A very
large push (scanning takes more than 30 seconds or reads more than 500 MB) is let through rather
than refused: the push prints `the rest of this push was not checked`, and the **Secret scanning**
page shows a banner that the push was too large to scan completely and went through unchecked.

To turn protection off for one repository, see
[Repository security features](security-features.md).

## Related

- `git.security.resolve-secret-alert` · `dcloud git security resolve-secret-alert`
