Lesson 8 of 8 in Git and collaboration
Keeping secrets out of git
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
- 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.
- .env file to git add .: 1 add everything
- git add . to Repository: 2 commit the rest
- .gitignore to git add .: skip matching files
- 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 Revoke it to 2 Issue a new one: then
- 2 Issue a new one to 3 Clean history: then
- 3 Clean history to 4 Tell the team: then
- 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.
- 1Make 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
.envas untracked. After the ignore rule it lists only.gitignore.git check-ignore -vnames the rule that matched, which is the first thing to run when a file is ignored or not ignored unexpectedly. - 2See 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.envis still listed as modified. Git keeps tracking a file it already knows, whatever.gitignoresays. - 3Stop 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 --cachedremoves the file from tracking and leaves it on disk. The-Soption searches history for commits that added or removed that text. It still finds the earlier commit, which shows why deleting is not enough. - 4Read 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, butgit statusstill 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, thengit 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 asgit filter-repoif 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
.gitignoreis 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.
Keep going
Lesson 38 of 92 in the DevOps path