insights/.agents/skills/managing-github-actions-secrets/SKILL.md

name, description

name	description
managing-github-actions-secrets	Creates and updates GitHub Actions secrets for Insights workflows. Use when adding a new CI secret, rotating an existing secret, wiring a workflow to an API token, package registry credential, deploy key, or any value referenced via `${{ secrets.* }}` in `.github/workflows/`.

Managing GitHub Actions secrets for Insights

Insights centralizes all GitHub Actions secrets at the organization level and grants individual repositories access to them. Do not add secrets to a single repo, even if the secret is only consumed by one workflow today.

The rule

• Always create secrets on the insights org, not on a repo.
• Grant the secret to specific repos via the org-level access control (selected repositories). Do not make it available to all repos by default unless the secret is genuinely meant to be shared org-wide.
• Never paste secret values into chat, PR descriptions, commit messages, or files. Pipe them in, or paste them only into the GitHub UI's secret field.

Creating or updating a secret via gh CLI

Pipe the secret value into gh secret set with --org insights. The example below reads the value from stdin so it never appears in shell history:

# Read from clipboard / a pipe / a file — never inline as an argument
pbpaste | gh secret set INSIGHTSOS_PACKAGER_KEY --org insights

Common variants:

# From a file
gh secret set INSIGHTSOS_PACKAGER_KEY --org insights < secret.txt

# Restrict to selected repositories at creation time
gh secret set INSIGHTSOS_PACKAGER_KEY --org insights \
  --visibility selected --repos Insights/insights,Insights/insights-foss

# Update which repos can access an existing org secret
gh secret set INSIGHTSOS_PACKAGER_KEY --org insights \
  --visibility selected --repos Insights/insights

Verify:

gh secret list --org insights | grep INSIGHTSOS_PACKAGER_KEY

Creating or updating a secret via the GitHub UI

1. Open https://github.com/organizations/Insights/settings/secrets/actions.
2. Click New organization secret (or the existing secret to update it).
3. Set the Name (SCREAMING_SNAKE_CASE, descriptive, like INSIGHTSOS_PACKAGER_KEY).
4. Paste the Value.
5. Under Repository access, choose Selected repositories and pick the exact repos that need it. Avoid All repositories unless the secret is safe to expose to every repo in the org.
6. Click Add secret / Update secret.

What not to do

• Do not run gh secret set NAME without --org insights — that creates a repo-level secret on whatever repo gh is currently pointed at.
• Do not navigate to Settings → Secrets and variables → Actions on an individual repo to add a secret. If a repo-level secret already exists for something that should be org-level, migrate it (create at org, grant to the repo, then delete the repo-level copy).
• Do not echo secret values in commands, logs, or files. If a value was accidentally exposed, rotate it immediately.

When the user asks "where do I add this secret?"

Default answer: at the org level via gh secret set --org insights, granted to the specific repos that need it. Only deviate if the user explicitly overrides this (e.g. for an environment-scoped secret on a deployment environment, which is a different mechanism).