Sign inOpen the board

Set up Sign in with GitHub

About 5 minutes. You create a GitHub OAuth app, give Klio its Client ID and secret, and the Continue with GitHub button appears on the sign-in page.

GitHub sign-in is set up on this serverGITHUB_CLIENT_ID is present. If sign-in still fails, see Troubleshooting below.

1Create a GitHub OAuth app

  1. Open github.com/settings/developers → OAuth Apps → New OAuth App. (For an organization: the org's Settings → Developer settings → OAuth Apps.)
  2. Fill in the form. GitHub allows one callback URL per app, so make one app for local development and one for production.
    Application nameKlio (local) or Klio
    Homepage URLhttps://klio.dev
    Authorization callback URLhttps://klio.dev/api/auth/github/callback
    Enable Device FlowLeave off
    The callback must match exactly: http vs https, the port, and localhost vs 127.0.0.1 all count.
    terminal
    https://klio.dev/api/auth/github/callback
  3. Click Register application. Copy the Client ID, then Generate a new client secret and copy it right away. GitHub shows the secret only once.

2Local development

Add both values to .dev.vars in the Klio folder. That file is git-ignored; never commit it.

terminal
GITHUB_CLIENT_ID=paste-the-client-id
GITHUB_CLIENT_SECRET=paste-the-client-secret

Restart the dev server (Ctrl+C, then npm run dev). It reads .dev.vars only at startup. Use the callback http://localhost:3000/api/auth/github/callback if you run on the default port.

3Production (Cloudflare Workers)

Create a second OAuth app whose callback is https://klio.dev/api/auth/github/callback, then store its values as Worker secrets from the Klio folder. Each command prompts for the value, so it never lands in your shell history:

terminal
npx wrangler secret put GITHUB_CLIENT_ID
npx wrangler secret put GITHUB_CLIENT_SECRET

Also make sure:

  • APP_URL in wrangler.jsonc → vars is your production URL (https://klio.dev). Klio builds the callback from it. Redeploy with npm run deploy if you change it.
  • The other server secrets are set once: openssl rand -hex 32 | npx wrangler secret put SESSION_SECRET and the same for ENCRYPTION_KEY.

Secrets take effect on the next request; no redeploy needed for them.

4Check it works

  1. Open /login. You should see Continue with GitHub.
  2. Sign in. GitHub asks you to authorize the app once, then you land in Klio. Your first sign-in creates a workspace with a short tour project.

Klio asks GitHub only for read:user and user:email: your name, avatar and verified email. It gets no access to your repositories.

Troubleshooting

“GitHub sign-in isn't set up on this server yet”

GITHUB_CLIENT_ID isn't set where Klio runs. Locally, check .dev.vars and restart npm run dev. In production, run npx wrangler secret list and add it with npx wrangler secret put GITHUB_CLIENT_ID.

GitHub says “The redirect_uri is not associated with this application”

The callback URL in your OAuth app doesn't match where Klio is running. It must be exactly https://klio.dev/api/auth/github/callback for this server. Edit it under the OAuth app's settings, or use the app made for this environment.

“That sign-in attempt expired. Try again.”

The sign-in took longer than 10 minutes, or you started on one address and came back on another (for example 127.0.0.1 vs localhost). Start again from the same address as APP_URL.

“GitHub didn't accept the sign-in.”

The Client ID and secret don't belong together. This usually means the secret was regenerated or mistyped, or the ID is from the other environment's app. Generate a new client secret and set both values again.

“Your GitHub account has no verified email.”

Add and verify an email at github.com/settings/emails, or sign in with an email link instead.

“You cancelled the GitHub sign-in.”

You clicked Cancel on GitHub's authorization screen. Click Continue with GitHub again and choose Authorize.

Optional: move stories from pull requests

Sign-in and PR sync are separate. To have PRs and commits that mention a story ID (like KLIO-12) move it on the board, add a webhook to each repo: Settings → Webhooks → Add webhook.

Payload URLhttps://klio.dev/api/github/webhook?token=klio_… (a token from Settings → Connect agents)
Content typeapplication/json
EventsPull requests and Pushes
SecretOptional. If you set one, store the same value with npx wrangler secret put GITHUB_WEBHOOK_SECRET.