> ## Documentation Index
> Fetch the complete documentation index at: https://nango.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# CI/CD for Nango Functions

> How to integrate Nango Function deployments into your CI/CD pipeline.

CI/CD for Nango is about keeping your [Functions](/guides/functions/functions-guide) — sync functions, action functions, webhook functions, and event functions — in sync with your application across environments.

The core principle: **deploy to Nango as part of the same pipeline step as your application**. Deploying them separately risks your app and your Functions going out of sync, which can cause subtle bugs that are hard to trace.

## Authentication

To deploy from CI, you need a scoped API key for each Nango environment.

1. **Create API keys**: In the Nango UI, go to **Environment Settings > API Keys** and create a key for each environment (e.g., `dev` and `prod`). For CI/CD pipelines, use a key scoped to `environment:deploy` only — see the [CI/CD Deploy profile](/reference/backend/http-api/api-keys#cicd-deploy).
2. **Store the keys**: Add them as secrets in your CI/CD provider. The Nango CLI reads them from these environment variables:
   * `NANGO_SECRET_KEY_DEV`
   * `NANGO_SECRET_KEY_PROD`

## Recommended pipeline

Treat Nango Functions like application code: validate on every PR, deploy to each environment in the same step as your application.

| Pipeline stage            | What to do                                                                     |
| ------------------------- | ------------------------------------------------------------------------------ |
| **Pull request**          | Run `nango compile` and `npm test` as required checks. Block merge on failure. |
| **Merge to main**         | Deploy to your dev/staging Nango environment alongside your app.               |
| **Release to production** | Deploy to your prod Nango environment in the same step as your app release.    |

The Nango CLI `deploy` command targets a specific environment:

```bash theme={null}
nango deploy <environment>
```

If you don't specify an environment, it defaults to `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.

<Info>
  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.
</Info>

## Example: GitHub Actions

Two workflow files implement the pipeline above.

<AccordionGroup>
  <Accordion title="PR validation (.github/workflows/nango-validate.yml)">
    ```yaml theme={null}
    name: Validate Nango Functions

    on:
      pull_request:
        branches:
          - main

    jobs:
      validate:
        runs-on: ubuntu-latest

        steps:
          - name: Checkout code
            uses: actions/checkout@v4

          - name: Set up Node.js
            uses: actions/setup-node@v4
            with:
              node-version: '20'

          - name: Install dependencies
            run: npm ci

          - name: Compile
            run: npx nango@latest compile --no-dependency-update

          - name: Test
            run: npm test
    ```
  </Accordion>

  <Accordion title="Deploy (.github/workflows/nango-deploy.yml)">
    ```yaml theme={null}
    name: Deploy Nango Functions

    on:
      # Manual trigger to deploy to a specific environment
      workflow_dispatch:
        inputs:
          stage:
            type: choice
            description: 'Environment to deploy to'
            required: true
            default: 'dev'
            options:
              - dev
              - prod
          allowDestructive:
            type: boolean
            description: 'Allow destructive changes'
            required: true
            default: false

      # Automatic deploy to dev on merge to main
      push:
        branches:
          - main

    jobs:
      deploy:
        runs-on: ubuntu-latest
        env:
          NANGO_SECRET_KEY_DEV: ${{ secrets.NANGO_SECRET_KEY_DEV }}
          NANGO_SECRET_KEY_PROD: ${{ secrets.NANGO_SECRET_KEY_PROD }}

        steps:
          - name: Checkout code
            uses: actions/checkout@v4

          - name: Set up Node.js
            uses: actions/setup-node@v4
            with:
              node-version: '20'

          - name: Install dependencies
            run: npm ci

          - name: Deploy to Nango
            run: |
              if [ "${{ github.event_name }}" == "workflow_dispatch" ]; then
                stage="${{ inputs.stage }}"
              else
                stage="dev"
              fi

              secret_key_var="NANGO_SECRET_KEY_$(echo "$stage" | tr '[:lower:]' '[:upper:]')"
              secret_key="${!secret_key_var}"

              if [ -z "$secret_key" ]; then
                echo "Error: ${secret_key_var} is not set"
                exit 1
              fi

              destructive_flag=""
              if [ "${{ github.event_name }}" == "workflow_dispatch" ] && [ "${{ inputs.allowDestructive }}" == "true" ]; then
                destructive_flag="--allow-destructive"
              fi

              npx nango@latest deploy "$stage" --secret-key "$secret_key" --no-dependency-update $destructive_flag
    ```
  </Accordion>
</AccordionGroup>

<Warning>
  **Destructive Changes**

  A destructive change removes an integration, sync function, or action function. To prevent accidental deletions, `nango deploy` will prompt for confirmation when it detects one.

  In CI, use `--auto-confirm` or `--allow-destructive` to bypass the prompt. We recommend only doing this on a manual trigger, as shown above.
</Warning>

## 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:

```bash theme={null}
npm test
```

See the [Testing integrations guide](/guides/functions/testing) for details.

## 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.

<Info>
  Nango doesn't currently support creating environments programmatically. This is on the roadmap and will make ephemeral environment setups much cleaner when available.
</Info>

For now, the simplest approach is to designate a fixed, long-lived Nango environment (e.g., `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 modifying `package.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:

```bash theme={null}
npx nango@latest deploy dev --no-dependency-update
```

<Warning>
  With `--no-dependency-update`, Nango will not install dependencies. Make sure your pipeline does so first (e.g. `npm ci`, `pnpm install --frozen-lockfile`, `yarn install --immutable`, or `bun install --frozen-lockfile`).
</Warning>

<Info>
  In CI environments, Nango automatically disables dependency updates to prevent modifying `package.json`. Passing `--no-dependency-update` explicitly silences the related warning.
</Info>

## Related resources

* [Testing integrations](/guides/functions/testing) - A comprehensive guide to testing your Nango Functions.
* [API Keys reference](/reference/backend/http-api/api-keys) - Available scopes and advised profiles for CI/CD and other use cases.