// Guide agents through registering, configuring, and installing a GitHub App for use with the-power. Covers private key generation, .gh-api-examples.conf setup, JWT creation, installation token exchange, and verification.
| name | setup-github-app |
| description | Guide agents through registering, configuring, and installing a GitHub App for use with the-power. Covers private key generation, .gh-api-examples.conf setup, JWT creation, installation token exchange, and verification. |
| keywords | ["GitHub App","app","authentication","JWT","token","installation","private key","app ID","client ID","ghs","tiny"] |
Walk through creating a GitHub App and configuring the-power to authenticate
with it. At the end you will have a working ghs_ installation token.
All scripts must be run from the root of a the-power repository clone
(the directory containing .gh-api-examples.conf).
Find an existing clone:
find ~ -maxdepth 5 -name "tiny-dump-app-token.sh" -path "*/the-power/*" 2>/dev/null
.gh-api-examples.conf must exist (see the configure skill).
A GitHub organisation where you have admin access.
The Ruby JWT gem:
sudo gem install jwt
In the GitHub UI navigate to:
Organisation → Settings → Developer settings → GitHub Apps → New GitHub App
Fill in the basics:
| Field | Example value |
|---|---|
| App name | test-app (must be unique across GitHub) |
| Homepage URL | https://example.com/homepage |
| Webhook URL | https://example.com/webhook or a smee.io channel |
Choose the permissions the app needs for the scripts you plan to run. Start with a minimal set and add more later — but remember to approve permission changes in the installation UI (see below).
Click Create GitHub App. You will land on the app's settings page.
On the app settings page, scroll to Private keys and click
Generate a private key. A .pem file downloads automatically.
Keep it safe — you need the path to this file in step 6.
In the left sidebar click Install App, then Install next to your organisation. Choose repository access (all or selected).
Set the GitHub App values in .gh-api-examples.conf:
python3 gh-set-value.py --key private_pem_file --value /path/to/your-app.private-key.pem
python3 gh-set-value.py --key default_app_id --value <App ID>
python3 gh-set-value.py --key client_id --value <Client ID>
python3 gh-set-value.py --key default_installation_id --value <Installation ID>
./tiny-dump-app-token.sh
Expected output:
++++++++++++++++++++++ App Token ++++++++++++++++++++++
ghs_w0wTh1sReAlLyIsAToKeN0rSomETH1nGLoOKSgrEAt
+++++++++++++++++++++++++++++++++++++++++++++++++++++++
If you see a ghs_ token, the app is working.
| ID | Where to find it |
|---|---|
| App ID | Organisation → Settings → Developer settings → GitHub Apps → your app (near the top) |
| Client ID | Same page as App ID |
| Installation ID | Organisation → Settings → GitHub Apps → gear icon → check the URL: .../installations/<ID> |
When you update an app's permissions, you must approve the change in the installation UI:
If you skip this, the permission change will not take effect.
| Script | Purpose |
|---|---|
tiny-get-jwt.py | Generate a JWT from the private key (Python) |
tiny-get-jwt.rb | Generate a JWT from the private key (Ruby) |
tiny-call-get-jwt.sh | Shell wrapper that calls tiny-get-jwt.rb |
tiny-call-get-installation-token.sh | Exchange JWT for an installation access token |
tiny-dump-app-token.sh | End-to-end: generate JWT → get token → print it |
tiny-get-an-app.sh | Get app metadata |
tiny-list-app-installations.sh | List app installations |
create-an-installation-access-token-for-an-app-modified-permissions.sh | Token with custom permissions |
create-an-installation-access-token-for-an-app-selected-repo-modified-permissions.sh | Token scoped to specific repos |
docs/setting-up-a-gh-app.md in the-powerdefault_installation_id does not
match an active installation..pem files to any repository..gh-api-examples.conf directly unless asked. Use
python3 gh-set-value.py to change individual values.Clean up GitHub resources created by the-power test environment scripts. Delete repositories, teams, members, rulesets, webhooks, environments, and other resources. Suspend or unsuspend users on GHES.
Configure the-power for a target GitHub instance. Run configure.py to generate .gh-api-examples.conf with hostname, token, org, repo, and other settings. Covers interactive and non-interactive setup, GHES vs dotcom differences, curl flags for self-signed certs, and GitHub App configuration.
Create a fully populated test organisation on a GitHub instance using the-power's build-all.sh script. Includes users, teams, repos, PRs, branch protection, and more. Requires .gh-api-examples.conf to be configured first.
Create a test repository using the-power's build-testcase scripts. Covers the full decision matrix of 30+ testcase scripts for repos with PRs, issues, workflows, secret scanning, rulesets, runners, and more.
Find the right the-power script by category, keyword, or goal. Covers all ~980 scripts organised by operation type with safety labels for destructive, GHES-only, and bulk operations.
Execute any the-power script with guided parameter input. Covers prerequisites, working directory, output interpretation, HTTP status codes, error patterns, and debugging techniques.