Keeping track of secrets and when they expire

Every project depends on credentials and settings that live somewhere else: an app secret for sign-in and mail, an access token for the code host, an API key for a service, a certificate, an environment setting. Some of them expire on a fixed date, and nobody remembers the date until something stops working. The Secrets tab on a project, and the Secrets page in the Work menu, keep the list in one place with the dates that matter.

What to record

Record the facts about a secret, never the value itself. For each one:

• a name people will recognise, such as “Microsoft app secret for mail and sign-in”;
• its kind (API key, client secret, certificate, token, password, environment variable, configuration or other) and its environment (Production, Staging, Development or All);
• the provider that issued it, and what it is used for;
• where it lives: where the real value is kept, for example the name of the setting it is stored in or the app registration it belongs to;
• the reference, the variable or setting name the code reads;
• an owner, the colleague who renews it;
• the date it expires, or tick Never expires;
• any notes worth keeping, such as “never regenerate: every phone subscription breaks”.

Open a project, go to Secrets, and click Add secret. The same form edits a secret later from the … menu on its row.

Expiry warnings

A secret with an expiry date shows how long it has left: in 12 days, today, 3 days ago. Within 30 days it is marked as expiring, and within 7 days the mark turns amber. Once the date has passed it reads as expired.

Warnings go out on their own, at 9 in the morning:

• 30, 14, 7 and 1 days before the date, and on the day itself, the owner, the project’s project managers and the project lead get a notification.
• From 7 days out, and once it has expired, leadership is added and everyone on the list gets an email as well.

Each warning is sent once. A secret added with 5 days left gets one “7 days” warning, not three.

The project overview shows Expiring or Expired with a count beside the project’s other facts, and the dashboard’s Expiring secrets card lists the five most urgent across every project you can see.

Rotating a secret

When a secret has been renewed, choose Mark rotated from its … menu. Give the date it was rotated (today unless you say otherwise) and the new expiry date, or tick Never expires. Leaving the new date blank keeps the current one. Marking a secret rotated starts its warnings again from the new date.

Retiring a secret

A secret that is no longer used can be retired from its … menu. It leaves the list and stops sending warnings. Turn on Show retired to see retired secrets, and click Restore to bring one back.

The Secrets page

Secrets lists the secrets of every project you can see, soonest to expire first. The four numbers at the top (Expired, Expiring, Active, Never expires) are filters too. Search by name, provider or reference, narrow by project, environment, kind or status, and click a row to open that project’s Secrets tab. Export CSV downloads what is on screen.

History

Adding, editing, rotating and retiring a secret each appear in the project’s Activity tab. Pick the Secrets chip to see only those.

Who can do what

• Project managers, senior engineers and leadership add, edit, rotate, retire and restore secrets.
• Engineers add, edit and rotate them, but cannot retire them.
• Clients do not see secrets at all.