Lesson 8 of 8 in Git and collaboration

Keeping secrets out of git

Core10 minWritten for Git 2.28 or newer

A secret is a password, token or key that grants access to something. Git history is permanent and widely copied, so a secret that is committed must be treated as exposed, and the fix starts with revoking it, not with deleting the file.

Draft. This lesson is written and waiting for a person to run every command and review it. It is safe to learn from, but check the official documentation for anything you depend on.

Read these first: Staging and writing commits, Remotes, fetch, push and pull requests

The problem this solves

Applications and pipelines need credentials: database passwords, cloud keys, API tokens. They are easy to leave in a config file or a .env file, and then git add . stages them with everything else.

Once a commit with a secret is pushed, it is copied to every clone and fork, and automated scanners look for exactly this. Deleting the file in a new commit does not help, because the old commit still contains it.

Prevention is cheap and cleanup is expensive. This concept shows the prevention tools and then the response order for when it goes wrong anyway.

How it works

How .gitignore keeps a secret file out
How .gitignore keeps a secret file outYour secret file sits in the folder, git add skips files matching .gitignore, and only the other files reach the repository when you commit.1 addeverything2 commit therestskip matching files.env fileholds the secretgit add .stages filesRepositorysaved history.gitignorelist of files to skip
  • Security
  • Control
  • Data
  • Other

Your secret file sits in the folder, git add skips files matching .gitignore, and only the other files reach the repository when you commit.

  1. .env file to git add .: 1 add everything
  2. git add . to Repository: 2 commit the rest
  3. .gitignore to git add .: skip matching files
If a secret was committed, do these in order
If a secret was committed, do these in orderRevoke the exposed secret first, issue a new one, then clean the history and tell the team, knowing that existing clones and forks keep their copies.thenthenthencannot reach1 Revoke itmake the old one useless2 Issue a new onestore it outside git3 Clean historyrewrite and force push4 Tell the teamre-clone, check forksOld clones, forksstill hold the secret
  • Security
  • Control
  • People and clients
  • Other

Revoke the exposed secret first, issue a new one, then clean the history and tell the team, knowing that existing clones and forks keep their copies.

  1. 1 Revoke it to 2 Issue a new one: then
  2. 2 Issue a new one to 3 Clean history: then
  3. 3 Clean history to 4 Tell the team: then
  4. 3 Clean history to Old clones, forks: cannot reach

A .gitignore file lists patterns for files git should leave alone. git add skips matching files that are not already tracked. Put credential files such as .env in it before you create them. Note the limit: it only works on files git is not tracking yet.

If a file was already committed, adding it to .gitignore changes nothing, and removing it with git rm --cached only stops tracking it going forward. The earlier commits still hold the content. History can be rewritten with a tool such as git filter-repo, followed by a force push, but forks, old clones and any cached views on the hosting site may keep copies.

That is why the second diagram starts with revoking. Treat any pushed secret as public. Making the old key worthless solves the real problem, and cleaning history is tidying afterwards. Better still, keep secrets out of the repository by design: read them from environment variables or a secrets manager at runtime, and use a scanner such as gitleaks or your host's push protection to catch mistakes before they leave your machine.

Try it yourself

Everything here uses a fake value in a throwaway repository. Do not put a real credential in any step.

  1. 1
    Make a secret file and keep it out
    mkdir git-lab-7 && cd git-lab-7
    git init -b main
    git config user.name "Your Name"
    git config user.email "you@example.com"
    echo "API_KEY=not-a-real-key" > .env
    git status -s
    echo ".env" > .gitignore
    git status -s
    git check-ignore -v .env

    The first status lists .env as untracked. After the ignore rule it lists only .gitignore. git check-ignore -v names the rule that matched, which is the first thing to run when a file is ignored or not ignored unexpectedly.

  2. 2
    See that ignoring does not protect a tracked file
    git add .gitignore && git commit -m "Ignore .env"
    echo "TOKEN=fake-value-123" > old.env
    git add old.env && git commit -m "Add old.env by mistake"
    echo "old.env" >> .gitignore
    echo "more" >> old.env
    git status -s

    old.env is still listed as modified. Git keeps tracking a file it already knows, whatever .gitignore says.

  3. 3
    Stop tracking it, then look at history
    git rm --cached old.env
    git commit -am "Stop tracking old.env"
    git log --oneline -S"fake-value-123"

    git rm --cached removes the file from tracking and leaves it on disk. The -S option searches history for commits that added or removed that text. It still finds the earlier commit, which shows why deleting is not enough.

  4. 4
    Read a value from the environment instead
    export API_KEY="not-a-real-key"
    sh -c 'echo "the program sees: $API_KEY"'

    You should see

    the program sees: not-a-real-key

    The program gets its secret from the environment at run time. Pipelines supply the same variables from their own secret storage, so the file never exists in the repository.

What breaks, and where to look

  • You added a file to .gitignore, but git status still shows changes to it.

    WHY IT HAPPENS
    The file was committed earlier. Git keeps tracking tracked files regardless of .gitignore.
    CHECK FIRST
    Run git ls-files | grep <name> to confirm it is tracked, then git rm --cached <name> and commit. If it held a real secret, continue with the revoke steps.
  • You deleted a pushed secret in a new commit, but a scanner alert still fires, or the key still appears in git log -p.

    WHY IT HAPPENS
    History keeps every old version. The earlier commit and everyone's copy of it still contain the secret.
    CHECK FIRST
    Run git log --all --oneline -S'<a unique piece of the secret>' to find the commits. Revoke the secret first, then rewrite history with a tool such as git filter-repo if you still need to.
  • After you rewrote history and force-pushed, the secret comes back, or teammates see rejected pushes.

    WHY IT HAPPENS
    People with old clones still have the old commits, and pushing from them can bring the secret back. Forks keep their own copies as well.
    CHECK FIRST
    Ask everyone to re-clone, or to carefully clean their copy. Check forks and open pull requests. Contact your hosting platform's support about cached views if needed. This is why revoking comes first.

When not to use this

  • .gitignore is a convenience for untracked files, not a security control. Use a scanner or push protection to enforce the rule.
  • Rewriting history is disruptive: commit IDs change and open pull requests can break. If the secret has already been revoked and rotated, leaving the history alone is often the better choice.
  • A private repository is not a safe place for secrets either. Access changes, people leave, and repositories get copied. Keep secrets in a secrets manager.

Check yourself

Why does .gitignore not help with a file that is already committed?

It only affects files git is not tracking. Tracked files stay tracked, and earlier commits keep their content.

What is the first step when a secret was pushed?

Revoke or rotate it so the exposed value no longer works. Cleaning history comes after.

Why is deleting the file in a new commit not enough?

The earlier commit still contains the secret, and every clone and fork has a copy of that commit.

Lesson 38 of 92 in the DevOps path

Search

Search cheat sheets and projects