Skip to main content
Establish a recommended workflow for integrating Nango into your Continuous Integration (CI) and Continuous Deployment (CD) processes. This enables you to automate the testing and deployment of your Nango integrations across multiple environments (e.g., development and production).

​
Multi-Stage Deployments

We recommend a multi-stage deployment strategy to separate your development and production environments. This allows you to test changes in a dev environment before promoting them to prod. A common pattern is to automatically deploy to dev when changes are merged to your main branch, while using a manual approval step for deployments to prod. The Nango CLI supports this via the deploy command, which can target a specific stage: 
nango deploy <stage>
If you don’t specify a stage, it defaults to dev.

​
Authentication

To deploy from a CI script, you need to authenticate using a secret key for each stage.
  1. Generate Secret Keys: In the Nango UI, go to Settings > Secret Keys and generate a secret key for each stage (e.g., dev and prod).
  2. Store the Secret Keys: Store these keys as secrets in your CI/CD provider. We recommend naming them based on the stage, for example:
    • NANGO_SECRET_KEY_DEV
    • NANGO_SECRET_KEY_PROD

​
Example: GitHub Actions

Here is an example of a GitHub Actions workflow that implements the multi-stage deployment strategy described above. You can find a complete example in the Nango GitHub Actions repository. 
# .github/workflows/nango-deploy.yml
name: Deploy Nango Integrations

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

  # 2. Automatic trigger on push to main
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    # Set secrets as environment variables
    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 tests
        run: |
          npm install
          npm test

      - name: Deploy to Nango
        run: |
          # Determine the stage to deploy to
          if [ "${{ github.event_name }}" == "workflow_dispatch" ]; then
            stage="${{ inputs.stage }}"
          elif [ "${{ github.ref }}" == "refs/heads/main" ]; then
            stage="dev" # Default to dev for pushes to main
          else
            echo "Not a deployable event. Exiting."
            exit 0
          fi

          # Select the appropriate secret key
          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} secret is not set"
            exit 1
          fi

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

          # Deploy to the selected stage
          npx nango@latest deploy "$stage" --secret-key "$secret_key" $destructive_flag
Destructive ChangesA destructive change is a modification that removes an integration, sync, or action. To prevent accidental deletions, the nango deploy command will prompt for confirmation if it detects a destructive change.In a CI environment, you can use the --auto-confirm or --allow-destructive flag to bypass this prompt. We recommend only using this with a manual trigger, as shown in the example.

​
Testing in CI

We strongly recommend running tests in your CI pipeline before every deployment. This is your first line of defense against regressions. Nango’s testing framework uses dry runs and snapshot testing to validate your integrations without affecting production data. You can run your entire test suite with a single command: 
npm test
See more in the Testing integrations guide.