neonctl in CI: browser auth opens, set NEON_API_KEY instead
Fixes neonctl hanging in CI by opening a browser for OAuth. Use when pipelines or SSH sessions stall because neonctl tries interactive browser authentication with nobody to click. Sets NEON_API_KEY so the CLI authenticates non-interactively. Not for invalid-key 401s or local interactive use.
neonctl in CI: browser auth opens, set NEONAPIKEY instead
TL;DR: neonctl defaults to browser-based login, which hangs forever where no browser exists. Create an API key in the Neon console and export it as NEONAPIKEY in the CI job (as a secret, never inline in logs). The CLI picks it up automatically and skips the browser entirely.
neonctl hangs waiting for browser authentication in CISteps
- In the Neon console, create an API key and copy it.
- Add it to the CI system as a secret env var named NEONAPIKEY. Expected: the job environment contains it without printing it.
- Rerun the pipeline. Expected: neonctl commands authenticate immediately with no browser step.
- Still hanging: confirm the variable name is exactly NEONAPIKEY and that the step exporting it runs before the neonctl call.
When this applies
- neonctl hanging in CI, Docker builds, or headless SSH waiting on browser auth
- scheduled jobs that worked locally but stall on the runner
- any non-interactive environment where neonctl previously relied on a cached browser session
When it doesn't
Authentication failedwith NEONAPIKEY already set — the key itself is bad, fix that- local interactive use where the browser flow is fine
- permission errors after successful auth (key scope problem)
Compatibility
neonctl; NEONAPIKEY env var; CI secret stores. Verified against the neonctl README and the community CI setup article.
Variant phrasings
- neonctl CI headless authentication
- neonctl NEONAPIKEY environment variable
- neonctl browser auth hang CI
Root cause
neonctl's default auth is an OAuth browser dance. In CI there is no browser and no one to complete the dance, so the CLI waits indefinitely. The env-var key path bypasses OAuth completely.
Edge cases
- never echo the key in job logs; mark the variable secret/masked in the CI UI
- cached browser credentials on a self-hosted runner can mask this until the cache expires
- rotate CI keys on a schedule; a leaked build log can expose them
Maintainer review
No maintainer verification is recorded for this version.
This records the version a maintainer checked. It does not assert that the version is the latest upstream release.