Excluding folders and files from secret scanning

You can customize secret scanning to exclude directories or files from analysis, by configuring a secret_scanning.yml file in your repository.

Who can use this feature?

Repository owners, organization owners, security managers, and users with the admin role

In this article

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

  1. On GitHub, navigate to the main page of the repository.

  2. 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.

    Screenshot of the main page of a repository. Above the list of files, a button, labeled "Add file," is outlined in dark orange. In the file tree view of the repository, a button with a plus sign icon is also outlined in dark orange.

  3. In the file name field, enter ".github/secret_scanning.yml".

  4. Under Edit new file, type paths-ignore: followed by the paths you want to exclude from secret scanning.

    YAML
    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"

    Note

    • 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.

Verifying that the folder is excluded from secret scanning

  1. Open a file in a directory that you have excluded from secret scanning
  2. Paste a pre-invalidated secret, or a test secret.
  3. Commit the change.
  4. On GitHub, navigate to the main page of the repository.
  5. Under the repository name, click Security. If you cannot see the "Security" tab, select the dropdown menu, and then click Security.
    Screenshot of a repository header showing the tabs. The "Security" tab is highlighted by a dark orange outline.
    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.