Secret

Repository Secrets

Manage repository secrets for GitHub Actions using the GitHub CLI (gh).

Arguments

$ARGUMENTS

Format: [action] [args...]

• list - List secrets (names only, values are hidden)
• set <name> - Set a secret
• delete <name> - Delete a secret
• sync - Sync secrets from .env file

Examples

/github:secret list
/github:secret set API_KEY
/github:secret delete OLD_SECRET
/github:secret sync .env.production

Instructions

Required GitHub CLI preflight

Before any workflow step, read ../../references/github-cli-preflight.md and complete it. Do not run workflow commands until gh installation and authentication are verified.

List Secrets

gh secret list

Format output:

Secret Name          Updated
───────────────────────────
API_KEY              2 days ago
DATABASE_URL         1 week ago
DEPLOY_TOKEN         3 months ago

Total: 3 secrets

Note: Secret values are never displayed.

Set Secret

1. Never accept or request a raw secret value in chat or command arguments. Ask the user for the name of an existing environment variable or a local file that already contains the value. Never print either value.

2. Validate secret name:

   • Must start with letter or underscore
   • Can only contain alphanumeric and underscores
   • Cannot start with GITHUB_ prefix

3. Set the secret without putting its value in argv: Show the verified repository and secret name and require explicit confirmation before reading or submitting the value. Then run:

   # From an existing environment variable (do not echo the value)
   secret_env_name="<ENV_VAR_NAME>"
   printenv "$secret_env_name" | gh secret set <name>
   
   # From file
   gh secret set <name> < secret.txt
   

4. Confirm:

   Secret 'API_KEY' has been set.
   

Delete Secret

1. Require explicit confirmation: Show the verified repository and secret name. Do not delete until the user confirms that exact target.

2. Delete:

   gh secret delete <name>
   

3. Confirm deletion:

   Secret 'OLD_SECRET' has been deleted.
   

Sync from .env File

1. Validate the path without printing file contents. Never run cat on a secrets file. Resolve the requested path, require a regular non-symlink file, and reject device files, directories, and paths outside the intended workspace unless the user explicitly selected them.

2. Generate an exact preview: Locate the bundled ../../scripts/secret_sync.py relative to this Skill's installed directory. Its preview and apply commands share one parser and reject duplicate, multiline, ambiguous, symlink, or non-regular inputs. It prints names only.

   python3 <plugin_root>/scripts/secret_sync.py preview --file "$secret_file"
   

   Record the SHA256 value printed to stderr as <preview_sha256>. This digest binds the later import to the exact file the user reviewed.

3. Show preview: Compare the exact names with gh secret list if the user needs new/existing status. Never claim per-name created/updated results unless that comparison was actually performed.

   Will sync the following secrets:
   - API_KEY (new)
   - DATABASE_URL (update)
   - CACHE_HOST (new)
   
   Continue? [y/N]
   

4. Require final confirmation: Show the verified repository, source path, and exact secret names. Do not show values. Import only after explicit confirmation.

5. Import the same validated file: Pass the verified repository explicitly. The helper sends each value to gh secret set through stdin, never argv.

   python3 <plugin_root>/scripts/secret_sync.py apply \
     --file "$secret_file" \
     --repo "<host>/<owner>/<repo>" \
     --expect-sha256 <preview_sha256>
   

   If the file changed after preview, the helper stops and requires a new preview and confirmation.

6. Report only verified results:

   Synced 3 secrets from .env.production
   Names submitted:
   - API_KEY
   - DATABASE_URL
   - CACHE_HOST
   

Environment Secrets

For organization-level or environment-specific secrets:

# Environment secrets
gh secret set <name> --env production

# List environment secrets
gh secret list --env production

Security Notes

• NEVER echo or log secret values
• NEVER put secret values in command arguments
• NEVER commit secrets to the repository
• Recommend using .env.example with placeholder values
• Secrets are encrypted and only exposed to workflows

Error Handling

• If not in repo: "Error: Not in a git repository"
• If no write access: "Error: You don't have permission to manage secrets"
• If secret not found: "Error: Secret '' not found"
• If invalid name: "Error: Secret name must start with letter/underscore and contain only alphanumeric/underscores"

Important

• This manages repository secrets, not environment variables
• For environment-specific secrets, use --env <environment>
• Changes take effect on next workflow run