From b4d5d601b92700f9e642328a8b255160b0f95bd0 Mon Sep 17 00:00:00 2001 From: Goose Date: Fri, 27 Mar 2026 11:06:57 +0000 Subject: [PATCH] feat: add --raw flag to github-app-token and clean up docs - Add --raw flag that prints only the token value (no export wrapper), making GH_TOKEN=$(./generate_token.sh --raw) the recommended pattern for AI agents and CI/CD. - Clean up die() to only write to stderr (remove eval-safe stdout hack). - Fix SKILL.md: correct step numbering, remove unused grep prerequisite, replace placeholder paths, lead with --raw usage, move eval to legacy. - Update CLAUDE.md to reflect new --raw pattern. Co-Authored-By: Paperclip --- CLAUDE.md | 4 +-- github-app-token/SKILL.md | 39 ++++++++++++---------- github-app-token/scripts/generate_token.sh | 18 ++++++++-- 3 files changed, 39 insertions(+), 22 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index dae022b..b641108 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -14,12 +14,12 @@ 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. The script outputs an `export GH_TOKEN=...` command meant to be `eval`'d by the caller. +- **`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. ## Key Patterns - Scripts are pure bash with no external dependencies beyond standard Unix tools (`openssl`, `curl`, `jq`). -- The `eval` output pattern: scripts print shell commands to stdout (e.g., `export VAR="value"`) so callers can `eval` the output to set variables in their environment. +- 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 index 1379888..80d0a0a 100644 --- a/github-app-token/SKILL.md +++ b/github-app-token/SKILL.md @@ -19,30 +19,23 @@ The following environment variables MUST be set before invoking this skill: If any variable is missing, stop and tell the user which ones are required. -Requires `openssl`, `curl`, `grep`, and `jq` (standard on modern environments). +Requires `openssl`, `curl`, and `jq` (standard on modern environments). ## Steps -### 1. Generate and Export Token +### 1. Generate a Token -Run the helper script and `eval` its output. This securely exports the short-lived GitHub installation access token as `GH_TOKEN` into your current process environment. - -**Important:** Because `eval` sets the variable in the current shell process, any commands that need `GH_TOKEN` must run in the **same shell invocation**. Chain all dependent commands together: +The simplest approach is to use `--raw` mode, which prints only the token value. This works reliably in a single shell invocation: ```bash -eval "$(/path/to/skills/github-app-token/scripts/generate_token.sh)" && gh api user +GH_TOKEN=$(./github-app-token/scripts/generate_token.sh --raw) && export GH_TOKEN ``` -Do NOT run `eval` in one command and then use `GH_TOKEN` in a separate command — the variable will not persist between separate shell invocations. +You can then use `GH_TOKEN` in subsequent commands within the same shell invocation: -> [!NOTE] -> For a CI/CD environment (like GitHub Actions), you can extract the token to pass it between steps like so: -> `echo "GH_TOKEN=$(/path/to/skills/github-app-token/scripts/generate_token.sh | cut -d'"' -f2)" >> $GITHUB_ENV` - -The script will: -1. Automatically construct a short-lived authorization assertion using your App ID and PEM key -2. Call the GitHub API to securely exchange that for an Installation Access Token -3. Output the `export GH_TOKEN="..."` command to set it in your environment. +```bash +GH_TOKEN=$(./github-app-token/scripts/generate_token.sh --raw) && export GH_TOKEN && gh api user +``` ### 2. Authenticate the gh CLI @@ -51,10 +44,10 @@ With `GH_TOKEN` set (in the same shell), the `gh` CLI operates securely and with To both generate the token and authenticate `gh` in one go: ```bash -eval "$(/path/to/skills/github-app-token/scripts/generate_token.sh)" && echo "${GH_TOKEN}" | gh auth login --with-token && gh auth status +GH_TOKEN=$(./github-app-token/scripts/generate_token.sh --raw) && export GH_TOKEN && echo "${GH_TOKEN}" | gh auth login --with-token && gh auth status ``` -### 4. Cleanup +### 3. Cleanup The installation access token expires after 1 hour. There is nothing to revoke unless you want to explicitly invalidate it early: @@ -65,6 +58,18 @@ curl -s -X DELETE \ "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 "$(./github-app-token/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=$(./github-app-token/scripts/generate_token.sh --raw)" >> $GITHUB_ENV` + ## Security Notes - Never log or echo the PEM key or installation token to stdout in production. diff --git a/github-app-token/scripts/generate_token.sh b/github-app-token/scripts/generate_token.sh index 130a49e..9b54c54 100755 --- a/github-app-token/scripts/generate_token.sh +++ b/github-app-token/scripts/generate_token.sh @@ -8,9 +8,17 @@ 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 - echo "return 1 2>/dev/null || false" exit 1 } @@ -62,5 +70,9 @@ if [[ -z "${INSTALL_TOKEN}" ]]; then die "failed to generate installation token. Response: ${RESPONSE}" fi -# Output the export command so it can be eval'd by the caller -echo "export GH_TOKEN=\"${INSTALL_TOKEN}\"" +# Output the token +if [[ "$RAW_MODE" == true ]]; then + printf '%s' "${INSTALL_TOKEN}" +else + echo "export GH_TOKEN=\"${INSTALL_TOKEN}\"" +fi