Pre-built integrations for self-managed Nango instances

The integration catalog is the set of Nango-maintained functions you can browse and deploy from the dashboard. On a Self-Managed instance, you upload its compiled files to your own object storage. Until you do, templates show up in the dashboard but fail when you run them.

This page is for Self-Managed instances only. If you run BYOC, Nango installs and updates the catalog for you.

Requirements

An access token from Nango. The integration catalog repository is private. Ask for a token in your shared Slack channel with Nango or email support@nango.dev.
Nango managed image managed-1.6.18 or later.
An object storage bucket (S3, GCS or Azure Blob Storage) configured for your instance’s compiled integration files. See Configure object storage.
git, node and npm on the machine that builds the catalog.
Your cloud provider’s CLI, signed in with write access to the bucket, on the machine that uploads the catalog:
- AWS: AWS CLI (aws)
- GCP: gsutil
- Azure: AzCopy (azcopy) for uploads and the Azure CLI (az) for verification

Configure object storage

Nango reads the catalog from the same object store it uses for your deployed functions. Set the variables for one provider on the server, jobs and runner services. If your instance already deploys functions to object storage, these are already set. Also set NANGO_ENTERPRISE=true. See the configuration reference for the full list of variables.

AWS (S3)
GCP (GCS)
Azure (Blob Storage)

Variable	Example	Purpose
`AWS_INTEGRATIONS_BUCKET_NAME`	`my-company-nango-integrations`	S3 bucket for compiled integration files
`AWS_INTEGRATIONS_REGION`	`us-west-2`	Region of the bucket

The workloads need permission to read and write objects in the bucket, for example through an IAM role.

Variable	Example	Purpose
`GCS_INTEGRATIONS_BUCKET_NAME`	`my-company-nango-integrations`	GCS bucket for compiled integration files

Nango authenticates with Application Default Credentials, so the workloads need permission to read and write objects in the bucket.

Variable	Example	Purpose
`AZURE_INTEGRATIONS_ACCOUNT_NAME`	`mycompanynango`	Storage account for compiled integration files
`AZURE_INTEGRATIONS_CONTAINER_NAME`	`integrations`	Blob container
`AZURE_INTEGRATIONS_ACCOUNT_KEY`	`••••••••`	Optional shared key. Omit it to use `DefaultAzureCredential`

Set the account name and container name together.

Set NANGO_FLAG_PROVIDER=env and NANGO_FEATURE_FLAG_TOOLS_CATALOG=true on the server and jobs services. Once an object store is configured, Nango reads catalog files from it.

Install the catalog

Find the matching catalog version

Each Nango image bundles catalog metadata built from one specific commit of the integration-templates repository. The files you upload must come from that same commit, or templates fail at runtime.To find it, clone the Nango repo and check out the commit your image was built from. That commit is the last part of the image tag:

nangohq/nango:managed-1.6.18-0.71.11-fe85242b81ab9d3ac808a72ca7bdd2788c8e86fb
                                     └──────────── Nango commit SHA ────────────┘

Check out that commit and read the integration-templates commit from the last update to the bundled catalog metadata:

git clone https://github.com/NangoHQ/nango
cd nango
git checkout <NANGO-COMMIT-SHA>
git log -1 --format=%s -- packages/shared/flows.zero.json

The SHA at the end of the output is the integration-templates commit to use in the next step:

chore(integration-templates): automatic update from https://github.com/NangoHQ/integration-templates/commit/<COMMIT-SHA>

Build the catalog at that commit

Clone the integration-templates repository, authenticating with your access token. Check out the commit from step 1 and compile:

cd ..  # leave the nango checkout from step 1
git clone https://github.com/NangoHQ/integration-templates
cd integration-templates
git checkout <COMMIT-SHA>
npm ci
npm run compile:integrations

This takes several minutes. The script sets its own 8 GB Node heap, so don’t override it. The output goes into integrations/<provider>/build/.

Verify the build

The compiled catalog metadata must be byte-identical to the metadata bundled in your image. Compare it with the file in the Nango checkout from step 1:

# from the integration-templates directory
shasum -a 256 internal/flows.zero.json
shasum -a 256 ../nango/packages/shared/flows.zero.json

The two hashes must match. If they differ, return to step 1, confirm you checked out the Nango commit from your image tag, and rebuild.

Upload to your bucket

Upload each provider’s folder to the templates-zero/ prefix in your bucket, so that integrations/github/... ends up at templates-zero/github/....

AWS (S3)
GCP (GCS)
Azure (Blob Storage)

BUCKET=<your-bucket>

for dir in integrations/*/; do
  [ -d "$dir/build" ] || continue
  integration=$(basename "$dir")
  aws s3 sync "$dir" "s3://$BUCKET/templates-zero/$integration"
done

aws s3 sync uploads in parallel. Add --delete to also remove files that no longer exist in the catalog.

BUCKET=<your-bucket>

for dir in integrations/*/; do
  [ -d "$dir/build" ] || continue
  integration=$(basename "$dir")
  gsutil -m rsync -r "$dir" "gs://$BUCKET/templates-zero/$integration"
done

-m uploads in parallel. Add -d to also remove files that no longer exist in the catalog.

Use AzCopy, not az storage blob upload-batch. The Azure CLI uploads blobs one at a time, which turns a full catalog into an hour-long step. AzCopy uploads in parallel and finishes in minutes.

# Reuse your existing `az login` session
export AZCOPY_AUTO_LOGIN_TYPE=AZCLI

for dir in integrations/*/; do
  [ -d "$dir/build" ] || continue
  azcopy copy "$dir" \
    "https://<ACCOUNT>.blob.core.windows.net/<CONTAINER>/templates-zero/" \
    --recursive
done

Authenticating through Microsoft Entra instead of an account key also works when shared key access is disabled on the storage account.AzCopy doesn’t delete files that were removed from the catalog. A template removed upstream stays in the container until you delete it.

Uploads overwrite existing files, so it’s safe to run them again.

Verify the install

First, check that a known file exists in your bucket:

AWS (S3)
GCP (GCS)
Azure (Blob Storage)

aws s3 ls "s3://$BUCKET/templates-zero/github/build/github_actions_create-issue.cjs"

gsutil ls "gs://$BUCKET/templates-zero/github/build/github_actions_create-issue.cjs"

az storage blob exists \
  --account-name <ACCOUNT> \
  --container-name <CONTAINER> \
  --auth-mode login \
  --name "templates-zero/github/build/github_actions_create-issue.cjs"

Then confirm it works end to end:

In the dashboard, open an integration with templates provided by Nango (see Use the template catalog).
Select an action with source “Nango catalog”.
Run the selected action via the Trigger action API or using the “Test run” button.

Update the catalog

When you upgrade your image, repeat the install steps with the new image tag. Your access token stays valid, so you don’t need to contact Nango again. Templates you already deployed keep the files they were deployed with, so deploy them again to pick up the new version.

Troubleshooting

Symptom	Likely cause
A template appears in the dashboard but the function stays `in progress`	The files aren’t in the bucket, or they came from a different commit than the one your image expects. Redo steps 1 to 4.
Template deploys fail on every attempt, even with files uploaded	Your image is older than `managed-1.6.18`. Upgrade first.

Self-Managed - deployment, configuration reference and updates.
BYOC - Nango manages the catalog for you.
Self-hosting overview - architecture and object storage.

Getting started

Guides

Reference

Pre-built integrations for self-managed Nango instances

Requirements

Configure object storage

Install the catalog

Update the catalog

Troubleshooting

​Requirements

​Configure object storage

​Install the catalog

​Update the catalog

​Troubleshooting

​Related guides

Requirements

Configure object storage

Install the catalog

Update the catalog

Troubleshooting

Related guides