Authenticate pks with GitHub

Get pks holding a working GitHub credential in a few minutes: run the login, approve the device code in a browser, and grant the GitHub App access to the repository you want to build. That credential is what later lets pks github runner start claim jobs and lets containers push back to the repository.

This page covers pks github init only. The full flag surface for the group is on the pks github reference.

1. Prerequisites

• A GitHub account with permission to install a GitHub App on the target repository or its owning organization. Only step 3 needs this; step 2 works with any account.
• A browser you can reach. The device-code flow needs one browser session to approve the code. It does not have to be on the same machine.
• A personal access token, if you prefer to skip the device-code flow. Required only for the --token path in step 2.

2. Authenticate

Run the login with no arguments:

pks github init

The command starts GitHub's OAuth device-code flow against the Agentics Live GitHub App (client ID Iv23liFv43zosMUb8t9y). It prints a user code and a verification URL, then polls GitHub every five seconds — backing off when GitHub answers slow_down — until you approve the code or it expires. The requested scopes are repo, user:email, and write:packages.

When approval lands, the token is stored in the pks credential store under ~/.pks-cli/. If a valid token is already stored, the command skips the device-code flow and reports that it's already authenticated — but if a repository URL was also given, it still proceeds to step 3 and checks/grants app access to that repository. Add --force to log in again anyway.

Option A — device code (recommended)

pks github init

Option B — personal access token

pks github init --token ghp_xxxxxxxxxxxx

The --token path stores the token and exits. It runs no device-code flow and performs no repository check, even if you also pass a repository URL.

Option C — your own GitHub App

pks github init https://github.com/owner/repo --client-id Iv1abcdefgh --app-slug my-app

--client-id replaces the Agentics Live client ID used for the device-code flow, and --app-slug replaces the slug used to build the app's install URL. Pass both when you run your own app.

3. Grant repository access

Pass a repository URL to have pks github init check that the app can actually see that repository:

pks github init https://github.com/owner/repo

If the app is not installed for that owner, the command opens the app's installation page in your browser and waits for you to press Enter. If the app is installed but scoped to a list of repositories that does not include this one, it opens the installation's settings page instead, waits for Enter, and then re-checks.

Accepted URL forms are https://github.com/owner/repo, http://github.com/owner/repo, github.com/owner/repo, and git@github.com:owner/repo, with or without a trailing .git. Anything else fails with a parse error.

Note. Once a repository URL triggers the install check, the command blocks on keyboard input. Run it interactively — this branch is not scriptable. Use pks github init with no URL, or --token, in automation.

4. Verify

pks github status

The command reports that pks is authenticated and exits with code 0. If it exits with code 1, no valid token is stored — go back to step 2. For token type, scopes, and expiry, add --verbose.

5. Options

The positional repoUrl argument is optional. Omitting it authenticates without checking any repository.

6. Troubleshooting

7. Next steps

• Check GitHub authentication status — inspect the token you just stored
• Register a repository with the runner — the next command in the runner setup path
• Self-hosted devcontainer runner — what the credential is ultimately for
• pks github reference — every command in the group in one place