Stop Leaking Secrets — Configuration (2/3) (2024)

Gitleaks-Action is a simple solution to prevent and detect secret leaks at your organization. Read the previous blog post in this series to get started. In this blog post we’ll cover how to configure your Gitleaks-Action using a Gitleaks configuration file.

One of the main benefits of using Gitleaks and Gitleaks-Action is the powerful and simple to use configuration file, gitleaks.toml. In this blog post we will focus on how to use custom configuration files in the context of Gitleaks-Action, but the information explained here can be used outside the context of a CI/CD environment.

By default, Gitleaks-Action uses the configuration file located here. At the time of writing there are over 150 secret types including a powerful generic secret rule. However, your organization might not care about the majority of the secrets listed in the default configuration.

There are two ways to do this:

1. You can put a file named .gitleaks.toml at the root of your repo. Gitleaks will automatically load that configuration file.
2. Alternatively, you can put the config file elsewhere in your repo and then set an env variable, GITLEAKS_CONFIG, in your job definition to point to it. This should be the relative path from the root of your repo.

Example below:

name: gitleaks
on: [pull_request, push, workflow_dispatch]
jobs:
 scan:
 name: gitleaks
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v3
 with:
 fetch-depth: 0
 - uses: gitleaks/gitleaks-action@v2
 env:
 GITLEAKS_CONFIG: path/to/config.toml
 GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 GITLEAKS_LICENSE: ${{ secrets.GITLEAKS_LICENSE}}

Check the Gitleaks-Action log to confirm a custom configuration file has been loaded. If you used method 1, you should see something like:

If you used method 2, you should see something like this:

You may be running Gitleaks on many repos and want some way to control the configuration that is used to scan all of those repos. If that’s the case you can add a run step in the job to download your central config file to be picked up by Gitleaks-Action. For example, adding this step will download a config file to the repo root directory and name it .gitleaks.toml:

— run: wget -O .gitleaks.toml https://raw.githubusercontent.com/zricethezav/gitleaks/master/config/gitleaks.toml.

Putting it all together:

name: gitleaks-action
on: [pull_request, push, workflow_dispatch]
jobs:
 scan:
 name: gitleaks-action
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v3
 with:
 fetch-depth: 0
 - run: wget -O .gitleaks.toml https://raw.githubusercontent.com/zricethezav/gitleaks/master/config/gitleaks.toml
 - uses: gitleaks/gitleaks-action@v2
 env:
 GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 GITLEAKS_LICENSE: ${{ secrets.GITLEAKS_LICENSE}}

Now you can change your config in one central place and those changes will be picked up by all the Gitleaks-Actions workflows that use it.

Your organization may have a central Gitleaks configuration full of rules that are required to run on all repos, but there might also be some repos that have specific rules. For example, your organization might rely heavily on a few different API providers, but there is only one repo that uses the PlanetScale API. In that case, you can use the wget method above to pull down a central config and extend it with a repo-specific config that contains an [extend] table.

See this repo for an example.

The workflow definition contains this run step:

— run: wget -O central-gitleaks.toml https://raw.githubusercontent.com/whoopsify/.github/main/.gitleaks.toml

This step downloads a central config from the organization’s .github repo and saves it to the repo root as central-gitleaks.toml.

Meanwhile, the repo root already contains a repo-specific config called .gitleaks.toml, which we learned earlier will automatically get picked up by Gitleaks-Action (see Using a custom config above).

This repo-specific config contains an [extend] table pointing to the central config that was downloaded using wget:

[extend]
path = "central-gitleaks.toml"

This tells Gitleaks that the rules in .gitleaks.toml should extend the rules in central-gitleaks.toml.

Now you have a repo-specific configuration that extends a central configuration.

Note that you can also extend the default Gitleaks configuration (which is updated every week or so with new rules) by setting the useDefault flag in your repo’s configuration:

[extend]
useDefault = true

This tells Gitleaks to treat the current config file as an extension of the default Gitleaks configuration file. Since Gitleaks-Action will always use the latest (or near-latest) version of Gitleaks, it will always have a very recent version of the default config.

You should have enough information to configure your GitHub organization with secret scanning. Whether you want to use a custom configuration for every repo, a central configuration that can handle many repos, or a repo-specific configuration that extends a central configuration — we got you covered! If you have any questions feel free to contact us at https://gitleaks.io/contact.html or open an issue on one of our repos (https://github.com/zricethezav/gitleaks and https://github.com/gitleaks/gitleaks-action).