feat: Generate GitHub App installation access tokens directly via a new script and update documentation.

github-app-token/SKILL.md

@@ -23,44 +23,32 @@ Requires `openssl`, `curl`, `grep`, and `jq` (standard on modern environments).
 
 ## Steps
 
-### 1. Generate a JWT
+### 1. Generate and Export Token
 
-Run the helper script bundled with this skill:
+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:
 
 ```bash
-TOKEN=$(bash /path/to/skills/github-app-token/scripts/generate_jwt.sh)
+eval "$(/path/to/skills/github-app-token/scripts/generate_token.sh)"
 ```
 
-The JWT uses:
-- **Algorithm**: RS256
-- **Header**: `{"alg": "RS256", "typ": "JWT"}`
-- **Payload**:
-  - `iat`: current time minus 60 seconds (clock drift buffer)
-  - `exp`: current time plus 600 seconds (10 minute max)
-  - `iss`: the `GITHUB_APP_ID`
+> [!NOTE] 
+> Because this uses `eval`, the token is scoped only to the current terminal session, process, or script that executes it. 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`
 
-### 2. Exchange the JWT for an installation access token
+The script will:
+1. Generate a short-lived JWT using your App ID and PEM key
+2. Exchange the JWT to get a GitHub Installation Access Token
+3. Output the `export GH_TOKEN=...` command to set it in your environment.
+### 2. Authenticate the gh CLI
+
+With `GH_TOKEN` set, 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!
 
 ```bash
-RESPONSE=$(curl -s -X POST \
-  -H "Authorization: Bearer ${TOKEN}" \
-  -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=$(echo "$RESPONSE" | grep -o '"token":"[^"]*"' | head -1 | cut -d'"' -f4)
+# Check that gh is working
+gh api user
 ```
 
-If the response contains an error (e.g., `401 Unauthorized`), check:
-1. The PEM key matches the App ID
-2. The Installation ID is valid for this App
-3. The system clock is accurate (JWT `iat`/`exp` are time-sensitive)
-
-### 3. Authenticate the gh CLI
-
-```bash
-echo "${INSTALL_TOKEN}" | gh auth login --with-token
-```
+*(Alternatively, to specifically configure gh auth locally, you can use: `echo "${GH_TOKEN}" | gh auth login --with-token`)*
 
 Verify it worked:
 
@@ -76,7 +64,7 @@ The installation access token expires after 1 hour. There is nothing to revoke u
 
 ```bash
 curl -s -X DELETE \
-  -H "Authorization: Bearer ${INSTALL_TOKEN}" \
+  -H "Authorization: Bearer ${GH_TOKEN}" \
   -H "Accept: application/vnd.github+json" \
   "https://api.github.com/installation/token"
 ```

github-app-token/scripts/generate_token.sh

@@ -47,5 +47,20 @@ SIG=$(printf '%s' "${SIGNED_CONTENT}" | openssl dgst -binary -sha256 -sign "${GI
 
 JWT=$(printf '%s.%s' "${SIGNED_CONTENT}" "${SIG}")
 
-# Echo the token to stdout as expected by the skill
-echo "${JWT}"
+# 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
+  echo "error: failed to generate installation token" >&2
+  echo "${RESPONSE}" >&2
+  exit 1
+fi
+
+# Output the export command so it can be eval'd by the caller
+echo "export GH_TOKEN=\"${INSTALL_TOKEN}\""