Authentication
To deploy from CI, you need a scoped API key for each Nango environment.- Create API keys: In the Nango UI, go to Environment Settings > API Keys and create a key for each environment (e.g.,
devandprod). For CI/CD pipelines, use a key scoped toenvironment:deployonly — see the CI/CD Deploy profile. - Store the keys: Add them as secrets in your CI/CD provider. The Nango CLI reads them from these environment variables:
NANGO_SECRET_KEY_DEVNANGO_SECRET_KEY_PROD
Coding agents running in CI can use the Management MCP server with an Environment API key instead of OAuth. See Use an API key instead for client configuration and scopes.
Recommended pipeline
Treat Nango Functions like application code: validate on every PR, deploy to each environment in the same step as your application.
The Nango CLI
deploy command targets a specific environment:
dev.
If you don’t have a staging environment, wire the prod Nango deploy directly to your production release step — use a workflow_dispatch trigger or equivalent manual approval. This keeps production deploys intentional, and ensures they always happen through CI using the prod API key rather than from a local machine.
Add the
dist/ folder inside your nango-integrations directory to .gitignore. The CLI writes compiled JS artifacts there, and committing them creates noisy diffs and risks deploying stale bundles.Example: GitHub Actions
Two workflow files implement the pipeline above.PR validation (.github/workflows/nango-validate.yml)
PR validation (.github/workflows/nango-validate.yml)
Deploy (.github/workflows/nango-deploy.yml)
Deploy (.github/workflows/nango-deploy.yml)
Testing in CI
Run your test suite in CI before every deployment. Nango’s testing framework uses dry runs and snapshot testing to validate your Functions without affecting live data:Ephemeral preview environments (e.g. Vercel)
If you use ephemeral preview environments — such as Vercel preview deployments — as your staging layer, you’ll run into a challenge: each preview has a unique URL, but Nango webhook URLs must be registered in advance and point to a stable destination.Nango doesn’t currently support creating environments programmatically. This is on the roadmap and will make ephemeral environment setups much cleaner when available.
dev) specifically for Nango-related changes, and use that consistently across preview deployments rather than trying to create a new Nango environment per preview.
If you need previews to receive live webhook events, a proxy server is the current workaround: register a stable URL in Nango, and have the proxy forward incoming webhooks to the correct preview URL.
Dependency-safe CI and monorepos
When running Nango in CI or monorepos, you often want to avoid modifyingpackage.json or running extra installs from within Nango commands. Use --no-dependency-update on CLI commands, or set NANGO_CLI_DEPENDENCY_UPDATE=false as an environment variable:
In CI environments, Nango automatically disables dependency updates to prevent modifying
package.json. Passing --no-dependency-update explicitly silences the related warning.Related resources
- Testing integrations - A comprehensive guide to testing your Nango Functions.
- API Keys reference - Available scopes and advised profiles for CI/CD and other use cases.