secret

name	secret
description	List, set, delete, or synchronize GitHub Actions repository secrets without exposing secret values. Use when the user explicitly wants to manage GitHub secret storage, not ordinary environment files or repository variables.

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