About secret scanning
Secret scanning automatically detects tokens or credentials that have been checked into a repository. You can view secret scanning alerts for users for any secrets that GitHub finds in your code, in the Security tab of the repository, so that you know which tokens or credentials to treat as compromised.For more information, see "About secret scanning alerts."
About excluding directories from secret scanning alerts for users
You may have a reason to commit a secret to a repository, such as when you want to provide a fake secret in documentation, or in an example application. In these scenarios, you can quickly dismiss the alert and document the reasons. However, there may be cases where you want to ignore a directory entirely to avoid creating false positive alerts at scale. For example, you might have a monolithic application with several integrations containing a file of dummy keys that could set off numerous false alerts to triage.
You can configure a secret_scanning.yml
file to exclude directories from secret scanning, including when you use push protection.
Excluding directories from secret scanning alerts for users
-
On GitHub, navigate to the main page of the repository.
-
Above the list of files, select the Add file dropdown menu, then click Create new file.
Alternatively, you can click in the file tree view on the left.
-
In the file name field, enter ".github/secret_scanning.yml".
-
Under Edit new file, type
paths-ignore:
followed by the paths you want to exclude from secret scanning.YAML paths-ignore: - "docs/**"
paths-ignore: - "docs/**"
This tells secret scanning to ignore everything in the
docs
directory. You can use this example file as a template to add the files and folders you’d like to exclude from your own repositories.You can also use special characters, such as
*
to filter paths. For more information about filter patterns, see "Workflow syntax for GitHub Actions."YAML paths-ignore: - "foo/bar/*.js"
paths-ignore: - "foo/bar/*.js"
Notes:
- If there are more than 1,000 entries in
paths-ignore
, secret scanning will only exclude the first 1,000 directories from scans. - If
secret_scanning.yml
is larger than 1 MB, secret scanning will ignore the entire file.
- If there are more than 1,000 entries in
Verifying that the folder is excluded from secret scanning
- Open a file in a directory that you have excluded from secret scanning
- Paste a pre-invalidated secret, or a test secret.
- Commit the change.
- On GitHub, navigate to the main page of the repository.
- Under the repository name, click Security. If you cannot see the "Security" tab, select the dropdown menu, and then click Security. There should be no new open alerts for the secret you just introduced into the file.
Best practices
Best practices include:
- Minimizing the number of directories excluded and being as precise as possible when defining exclusions. This ensures that the instructions are as clear as possible, and that exclusions work as intended.
- Explaining why a particular file or folder is excluded in a comment in the
secret_scanning.yml
file. As with regular code, using comments clarifies your intention, making it easier for others to understand the desired behavior. - Reviewing the
secret_scanning.yml
file on a regular basis. Some exclusions may no longer apply with time, and it is good practice to keep the file clean and current. The use of comments, as advised above, can help with this. - Informing the security team what files and folders you've excluded, and why. Good communication is vital in ensuring that everyone is on the same page, and understands why specific folders or files are excluded.