forked from farhoodlabs/skills
Chris Farhood
dedb35953b
Replaced generate_jwt.py with generate_jwt.sh using only openssl and coreutils. Updated SKILL.md to remove the python fallback section and use grep/cut for JSON parsing instead of python3.
89 lines
2.6 KiB
Markdown
89 lines
2.6 KiB
Markdown
---
|
|
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 `grep` (standard on macOS and Linux).
|
|
|
|
## Steps
|
|
|
|
### 1. Generate a JWT
|
|
|
|
Run the helper script bundled with this skill:
|
|
|
|
```bash
|
|
TOKEN=$(bash /path/to/skills/github-app-token/scripts/generate_jwt.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`
|
|
|
|
### 2. Exchange the JWT for an installation access token
|
|
|
|
```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)
|
|
```
|
|
|
|
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"
|
|
```
|
|
|
|
## 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.
|