Secrets Management for Small Teams

Every codebase has one area everyone is a little afraid to touch. On our team, it was everything related to secrets management.

When we finally measured, the numbers were worse than anyone guessed. Around 44% of the time spent on a typical change went into working around secrets management rather than building anything.

Some background

The first symptom was subtle. Nothing failed outright, but secrets management kept drifting in the wrong direction, and every fix seemed to make the next one harder.

We had good intentions. We even had a document describing how secrets management should work. The trouble was that the document and the code had quietly gone their separate ways.

What we changed

We started by writing down the one rule we actually cared about, then deleted every bit of code that didn't serve it. It's not glamorous, but it works.

Stripped of the project-specific bits, it looks like this:

- name: Cache dependencies
  uses: actions/cache@v4
  with:
    path: ~/.npm
    key: npm-${{ hashFiles('package-lock.json') }}
    restore-keys: npm-

Nothing about this is clever, and that's the point. Anyone on the team can read it in a minute and know exactly what it does.

A few things that helped along the way:

Measure before and after, even if it's just a rough number in a spreadsheet.
Pair on the first few changes so the knowledge doesn't live in one head.
Agree on what "done" means before the first pull request.
Keep the old path around until the new one has survived a real incident.

Caveats

None of this is free. The new approach is a bit more verbose, and newcomers occasionally ask why we don't just use Ansible for everything. That's a fair question with a boring answer: we tried, and it made secrets management harder to reason about.

The biggest cost was social, not technical. Changing how people think about secrets management takes much longer than changing the code.

Closing thoughts

I don't think there's a universal answer here, but I hope this gives you a few ideas to try on your own project. If you do, I'd love to hear how it goes.