neonctl "not authenticated" (NEON_API_KEY) in CI

By Kaveh Alemi·Latchkey

neonctl normally logs in through a browser, which cannot happen in CI. Without an API key it has no credentials and reports that you are not authenticated. Set NEON_API_KEY so the CLI authenticates non-interactively.

What this error means

A neonctl command (branches create, connection-string) fails with "You are not authenticated. Please run neonctl auth" and exits non-zero in the workflow.

ERROR: You are not authenticated. Run `neonctl auth` or set the NEON_API_KEY
environment variable to a valid API key.

Common causes

No API key in the environment

The CLI tries an interactive OAuth login. In CI there is no browser, so it falls back to looking for NEON_API_KEY, which is unset.

The key was set on the wrong scope

A key set only on a later step, or misnamed, is not visible to the neonctl step, so it still reports no credentials.

How to fix it

Provide NEON_API_KEY as a secret

1. Create an API key in the Neon console under Account settings.
2. Store it as a repository or organization secret.
3. Expose it to every step that calls neonctl.

env:
  NEON_API_KEY: ${{ secrets.NEON_API_KEY }}
run: neonctl projects list

Pass the key inline for a one-off command

You can pass the key with --api-key instead of the env var when scripting a single call.

neonctl branches list --api-key "$NEON_API_KEY" --project-id "$NEON_PROJECT_ID"

How to prevent it

• Set NEON_API_KEY at the job level so every neonctl step inherits it.
• Never commit the key; keep it in CI secrets and rotate it periodically.
• Scope the key to the project the workflow operates on.

Frequently asked questions

Related guides

References

• GitHub Actions documentation