commit 1b7356c61d0dbf315fd9bd635a66366ffbd5cb53 Author: Chris Farhood Date: Wed Mar 25 21:29:22 2026 -0400 feat: add github-app-token skill diff --git a/github-app-token/SKILL.md b/github-app-token/SKILL.md new file mode 100644 index 0000000..a5bb038 --- /dev/null +++ b/github-app-token/SKILL.md @@ -0,0 +1,105 @@ +--- +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. + +## Steps + +### 1. Generate a JWT + +Create a JWT signed with the GitHub App's private key. You MUST use the helper script bundled with this skill: + +```bash +# generates a JWT valid for 10 minutes +TOKEN=$(python3 "$(dirname "$0")/../skills/github-app-token/scripts/generate_jwt.py") +``` + +If `python3` is not available, fall back to the inline openssl method described in the Fallback section below. + +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` + +### 2. Exchange the JWT for an installation access token + +```bash +INSTALL_TOKEN=$(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" \ + | python3 -c "import sys,json; print(json.load(sys.stdin)['token'])") +``` + +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 +``` + +Verify it worked: + +```bash +gh auth status +``` + +You should see authentication via `token` for `github.com`. + +### 4. 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 ${INSTALL_TOKEN}" \ + -H "Accept: application/vnd.github+json" \ + "https://api.github.com/installation/token" +``` + +## Fallback: JWT generation without Python + +If `python3` is unavailable, generate the JWT using `openssl` and `bash`: + +```bash +header=$(printf '{"alg":"RS256","typ":"JWT"}' | openssl base64 -e -A | tr '+/' '-_' | tr -d '=') +now=$(date +%s) +iat=$((now - 60)) +exp=$((now + 600)) +payload=$(printf '{"iat":%d,"exp":%d,"iss":"%s"}' "$iat" "$exp" "$GITHUB_APP_ID" | openssl base64 -e -A | tr '+/' '-_' | tr -d '=') +unsigned="${header}.${payload}" +signature=$(printf '%s' "$unsigned" | openssl dgst -sha256 -sign "${GITHUB_APP_PEM_FILE}" -binary | openssl base64 -e -A | tr '+/' '-_' | tr -d '=') +TOKEN="${unsigned}.${signature}" +``` + +Then continue from Step 2. + +## Security Notes + +- Never log or echo the PEM key, JWT, or installation token to stdout in production. +- The JWT is valid for at most 10 minutes. The installation token is valid for 1 hour. +- Store the PEM file with restrictive permissions (`chmod 600`) and never check it into git. diff --git a/github-app-token/scripts/generate_jwt.py b/github-app-token/scripts/generate_jwt.py new file mode 100755 index 0000000..674f778 --- /dev/null +++ b/github-app-token/scripts/generate_jwt.py @@ -0,0 +1,98 @@ +#!/usr/bin/env python3 +"""Generate a JWT for GitHub App authentication. + +Reads from environment variables: + GITHUB_APP_ID - The GitHub App's numeric ID + GITHUB_APP_PEM_FILE - Path to the PEM-encoded private key file + +Prints the signed JWT to stdout. +""" + +import json +import os +import sys +import time +import base64 +import hashlib + +try: + from cryptography.hazmat.primitives import hashes, serialization + from cryptography.hazmat.primitives.asymmetric import padding + + USE_CRYPTOGRAPHY = True +except ImportError: + import subprocess + + USE_CRYPTOGRAPHY = False + + +def b64url(data: bytes) -> str: + return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii") + + +def sign_with_cryptography(unsigned: str, pem_key: str) -> str: + private_key = serialization.load_pem_private_key(pem_key.encode(), password=None) + signature = private_key.sign(unsigned.encode(), padding.PKCS1v15(), hashes.SHA256()) + return b64url(signature) + + +def sign_with_openssl(unsigned: str, pem_key: str) -> str: + result = subprocess.run( + ["openssl", "dgst", "-sha256", "-sign", "/dev/stdin"], + input=pem_key.encode(), + capture_output=True, + check=True, + env={**os.environ, "OPENSSL_CONF": "/dev/null"}, + ) + # openssl dgst -sign reads key from stdin on some versions, but not all. + # If that fails, write to a temp file. + if result.returncode != 0: + import tempfile + + with tempfile.NamedTemporaryFile(mode="w", suffix=".pem", delete=False) as f: + f.write(pem_key) + f.flush() + result = subprocess.run( + ["openssl", "dgst", "-sha256", "-sign", f.name], + input=unsigned.encode(), + capture_output=True, + check=True, + ) + os.unlink(f.name) + return b64url(result.stdout) + + +def main(): + app_id = os.environ.get("GITHUB_APP_ID") + pem_file = os.environ.get("GITHUB_APP_PEM_FILE") + + if not app_id: + print("error: GITHUB_APP_ID is not set", file=sys.stderr) + sys.exit(1) + if not pem_file: + print("error: GITHUB_APP_PEM_FILE is not set", file=sys.stderr) + sys.exit(1) + if not os.path.isfile(pem_file): + print(f"error: PEM file not found: {pem_file}", file=sys.stderr) + sys.exit(1) + + with open(pem_file, "r") as f: + pem_key = f.read() + + now = int(time.time()) + header = b64url(json.dumps({"alg": "RS256", "typ": "JWT"}).encode()) + payload = b64url( + json.dumps({"iat": now - 60, "exp": now + 600, "iss": app_id}).encode() + ) + unsigned = f"{header}.{payload}" + + if USE_CRYPTOGRAPHY: + signature = sign_with_cryptography(unsigned, pem_key) + else: + signature = sign_with_openssl(unsigned, pem_key) + + print(f"{unsigned}.{signature}") + + +if __name__ == "__main__": + main()