diff --git a/CLAUDE.md b/CLAUDE.md index fdec9f7..89e7f49 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -14,13 +14,11 @@ Each skill follows this convention: ## Current Skills -- **`github-app-token`** — Generates short-lived GitHub App installation access tokens. Requires `GITHUB_APP_ID`, `GITHUB_APP_INSTALLATION_ID`, and `GITHUB_APP_PEM_FILE` env vars. Use `--raw` flag to get the token value directly (recommended for agents), or omit for legacy `eval`-based `export GH_TOKEN=...` output. - **`playwright-ephemeral`** — Provisions ephemeral Playwright MCP browser sessions as Kubernetes Jobs for E2E testing. Creates a Job + Service pair in a dedicated namespace, waits for readiness, and returns the MCP endpoint URL. Requires `kubectl` and appropriate RBAC. ## Key Patterns - Scripts are pure bash with no external dependencies beyond standard Unix tools (`openssl`, `curl`, `jq`, `kubectl`). -- The `--raw` output pattern (preferred): scripts with `--raw` print only the value to stdout for easy `$(...)` capture. The legacy `eval` pattern (no flag) prints shell commands like `export VAR="value"` for backward compatibility. - The `die()` function prints errors to stderr and exits non-zero. ## No Build/Test/Lint System diff --git a/github-app-token/SKILL.md b/github-app-token/SKILL.md deleted file mode 100644 index 9c2aaf7..0000000 --- a/github-app-token/SKILL.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -name: github-app-token -description: Generate a GitHub installation access token from a GitHub App PEM key, App ID, and Installation ID, then authenticate the gh CLI with it. ---- - -# GitHub App Token Skill - -Generate a short-lived GitHub installation access token from a GitHub App's credentials and use it to authenticate the `gh` CLI. - -## Prerequisites - -The following environment variables MUST be set before invoking this skill: - -| Variable | Description | -|---|---| -| `GITHUB_APP_ID` | The numeric App ID from the GitHub App settings page | -| `GITHUB_APP_INSTALLATION_ID` | The numeric Installation ID for the target org/user | -| `GITHUB_APP_PEM_FILE` | Absolute path to the GitHub App's PEM private key file | - -If any variable is missing, stop and tell the user which ones are required. - -Requires `openssl`, `curl`, and `jq` (standard on modern environments). - -## Steps - -### 1. Generate a Token - -The simplest approach is to use `--raw` mode, which prints only the token value. This works reliably in a single shell invocation: - -```bash -GH_TOKEN=$(bash ./scripts/generate_token.sh --raw) && export GH_TOKEN -``` - -You can then use `GH_TOKEN` in subsequent commands within the same shell invocation: - -```bash -GH_TOKEN=$(bash ./scripts/generate_token.sh --raw) && export GH_TOKEN && gh api user -``` - -> **Note:** Using `bash` explicitly ensures the script runs even if the executable bit is not preserved in your environment. - -### 2. Authenticate the gh CLI - -With `GH_TOKEN` set (in the same shell), the `gh` CLI operates securely and without needing a separate authentication login for most API operations. Note that `gh auth status` may not reflect the token since it checks local config, but `gh` will respect the `GH_TOKEN` environment variable. - -To both generate the token and authenticate `gh` in one go: - -```bash -GH_TOKEN=$(bash ./scripts/generate_token.sh --raw) && export GH_TOKEN && echo "${GH_TOKEN}" | gh auth login --with-token && gh auth status -``` - -### 3. Cleanup - -The installation access token expires after 1 hour. There is nothing to revoke unless you want to explicitly invalidate it early: - -```bash -curl -s -X DELETE \ - -H "Authorization: Bearer ${GH_TOKEN}" \ - -H "Accept: application/vnd.github+json" \ - "https://api.github.com/installation/token" -``` - -## Advanced: `eval` Mode (Legacy) - -Without the `--raw` flag, the script outputs `export GH_TOKEN="..."` meant to be `eval`'d. This is the original behavior, preserved for backward compatibility: - -```bash -eval "$(bash ./scripts/generate_token.sh)" && gh api user -``` - -> [!NOTE] -> For CI/CD environments (like GitHub Actions), use `--raw` to extract the token cleanly: -> `echo "GH_TOKEN=$(bash ./scripts/generate_token.sh --raw)" >> $GITHUB_ENV` - -## Security Notes - -- Never log or echo the PEM key or installation token to stdout in production. -- The installation token represents your GitHub App and is strictly valid for 1 hour from generation. -- Store the PEM file with restrictive permissions (`chmod 600`) and never check it into git. diff --git a/github-app-token/scripts/generate_token.sh b/github-app-token/scripts/generate_token.sh deleted file mode 100755 index 9b54c54..0000000 --- a/github-app-token/scripts/generate_token.sh +++ /dev/null @@ -1,78 +0,0 @@ -#!/usr/bin/env bash -# Generate a GitHub App Installation Access Token and authenticate the gh CLI -# -# Required environment variables: -# GITHUB_APP_ID - The GitHub App's numeric ID -# GITHUB_APP_INSTALLATION_ID - The numeric Installation ID for the target org/user -# GITHUB_APP_PEM_FILE - Path to the PEM-encoded private key file - -set -euo pipefail - -# Parse flags -RAW_MODE=false -for arg in "$@"; do - case "$arg" in - --raw) RAW_MODE=true ;; - *) echo "error: unknown flag: $arg" >&2; exit 1 ;; - esac -done - -die() { - echo "error: $1" >&2 - exit 1 -} - -if [[ -z "${GITHUB_APP_ID:-}" ]]; then - die "GITHUB_APP_ID is not set" -fi - -if [[ -z "${GITHUB_APP_INSTALLATION_ID:-}" ]]; then - die "GITHUB_APP_INSTALLATION_ID is not set" -fi - -if [[ -z "${GITHUB_APP_PEM_FILE:-}" ]]; then - die "GITHUB_APP_PEM_FILE is not set" -fi - -if [[ ! -f "${GITHUB_APP_PEM_FILE}" ]]; then - die "PEM file not found: ${GITHUB_APP_PEM_FILE}" -fi - -# Function to base64 encode with URL-safe characters -b64enc() { openssl enc -base64 -A | tr '+/' '-_' | tr -d '='; } - -NOW=$(date +%s) -# JWT valid for 10 minutes (GitHub limit) -IAT=$NOW -EXP=$((NOW + 10 * 60)) - -# Create the JWT header and payload (requires jq for compact formatting just to be safe) -HEADER=$(printf '{"alg":"RS256","typ":"JWT"}' | jq -r -c .) -PAYLOAD=$(printf '{"iat":%s,"exp":%s,"iss":"%s"}' "${IAT}" "${EXP}" "${GITHUB_APP_ID}" | jq -r -c .) - -SIGNED_CONTENT=$(printf '%s' "${HEADER}" | b64enc).$(printf '%s' "${PAYLOAD}" | b64enc) - -# Sign the content with the private key -SIG=$(printf '%s' "${SIGNED_CONTENT}" | openssl dgst -binary -sha256 -sign "${GITHUB_APP_PEM_FILE}" | b64enc) - -JWT=$(printf '%s.%s' "${SIGNED_CONTENT}" "${SIG}") - -# Exchange JWT for an installation access token -RESPONSE=$(curl -s -X POST \ - -H "Authorization: Bearer ${JWT}" \ - -H "Accept: application/vnd.github+json" \ - -H "X-GitHub-Api-Version: 2022-11-28" \ - "https://api.github.com/app/installations/${GITHUB_APP_INSTALLATION_ID}/access_tokens") - -INSTALL_TOKEN=$(printf '%s' "${RESPONSE}" | jq -r '.token // empty') - -if [[ -z "${INSTALL_TOKEN}" ]]; then - die "failed to generate installation token. Response: ${RESPONSE}" -fi - -# Output the token -if [[ "$RAW_MODE" == true ]]; then - printf '%s' "${INSTALL_TOKEN}" -else - echo "export GH_TOKEN=\"${INSTALL_TOKEN}\"" -fi