Skip to content
Netlify SDK Docs Netlify SDK Docs 1.38.2

Publish and enable a private integration

With Private Integrations, you can create and add custom logic and tooling for only your Netlify team to use. Once created, Private Integrations can be enabled on a site or team level.

You can register and publish your integration as a private integration using the Netlify UI or the Netlify CLI.

Publishing a private data integration for Netlify Connect?

For details on how to register and publish your private data integration for Netlify Connect, refer to our publish a private data integration doc.

Integration metadata

When you register your integration, you need to provide the following information:

  • Name: human-friendly name of the integration. This will be displayed in the Netlify UI.

  • Slug: used to identify the integration in the Netlify UI. It must be unique across all integrations. Private Integrations have a nanoid that is generated automatically as part of the slug. Slugs without nanoids are reserved for partner integrations.

  • Description: brief summary of the integration and its functionality. This will be displayed in the Netlify UI.

  • Netlify integration site: a deployed Netlify site that contains your integration and its components. You can deploy the site manually with the Netlify UI or using the Netlify CLI. Note that a Netlify integration site can only be associated with one registered integration — you can’t register multiple integrations with the same integration site.

  • Integration level: the integration levels your integration will work on: site, team, or team-and-site.

  • Permission scopes: permission scopes that the integration needs to function properly.

    Use only the permission scopes you need

    We recommend that you only request the permission scopes that are required for your integration to function properly. Are we missing a scope that you’d like to use? Let us know through the feedback form at the bottom of this page.

Publish a private integration

You can can use the Netlify UI or the Netlify CLI to publish your private integration.

Prerequisites

Before you begin, make sure you have completed the following:

  • Make sure that your integration’s netlify.toml file includes the following:

    [build]
    command="netlify-integration build -a"
    publish=".ntli/site/static"
    

    [functions]
    directory=".ntli/site/netlify/functions"
    node_bundler = "esbuild"
    

    [[headers]]
    for="/ui/*"
    [headers.values]
    Access-Control-Allow-Origin="*"
    Access-Control-Allow-Headers="*"
    Access-Control-Allow-Methods="*"
    

    [dev]
    autoLaunch = false
    functions = ".ntli/site/netlify/functions"
    publish = ".ntli/site/static"

  • If you plan to use the Netlify CLI to publish your integration, ensure your integration.yaml file includes the following properties.

    • scopes
    • name
    • description
    • integrationLevel
    • slug

    For example:

    config:
      name: My Private Integration
      description: This is a cool integration!
      slug: my-private-integration
      scopes:
        site:
          - read
          - write
        env:
          - read
        user:
          - read
      integrationLevel: "team-and-site"

    Note that integrations for Netlify Connect require all permission scopes and the team integration level.

  • Push your integration code to a Git repository. Netlify will pull code from that repository as part of the deploy step.

Publish your integration with the Netlify UI

To register and publish your integration with the Netlify UI, you need to deploy your integration and then register it as a private integration.

Deploy your integration

Deploy your integration as a Netlify site:

  1. Log in to the Netlify UI.
  2. Create a new Netlify site by importing from the repository that you created for your integration. This site will be solely used for hosting the integration.

Register and publish your private integration

To register and publish your integration using the Netlify UI:

  1. Log in to the Netlify UI.
  2. Navigate to the team that owns your deployed integration site.
  3. Select the Integrations tab for your team to access the overview page for all your available integrations.
  4. Select Create a private integration
  5. Fill in and select the Display name, Slug, Description, Netlify integration site, Integration level, and Permission scopes for your integration.
  6. Select Create to finish.

Publish your integration with the Netlify CLI

The Netlify CLI has an integration command that can be used to build, deploy and register Private Integrations.

To get started, run netlify integration:deploy --build.

Register and publish a new private integration

To register and publish a new private integration using the Netlify CLI:

  1. Deploy your integration as a new integration site on Netlify by running netlify init or netlify deploy. Or link your repository to an existing integration site on Netlify using netlify link.
  2. Run netlify integration:deploy --build to start the registration process. This will also result in a build and deploy of your integration site.
  3. Follow the prompts to register your integration. The Netlify CLI will register the integration with Netlify using the information found in your integration’s integration.yaml file, as documented above under prerequisites.
  4. Once your integration is registered, the Netlify CLI will update the local copy of your integration.yaml file to reflect the registered integration slug. Commit and push the updated file to your repository after this change.

Once the deploy is complete, you can enable the integration for your team or site to use.

Update an existing private integration

To update an already registered and published private integration using the Netlify CLI:

  1. Run netlify integration:deploy --build. This will start the update process, and also kick off a new build and deploy of your integration site.
  2. The Netlify CLI will check for updates to the integration’s metadata in both the integration.yaml file and the Netlify UI. If there is a discrepancy between the two, the Netlify CLI will prompt you to select which values to use and then update the integration.yaml or Netlify UI values accordingly. Updates will only apply to future installations of your integration.
  3. If the Netlify CLI updated your local integration.yaml file in step 2, make sure to commit and push the update to your repository. This will kick off a new build and deploy of your integration site to ensure the latest version is available when users enable the integration.

Once the deploy is complete, any new teams or sites that enable your integration will access the latest version.

Enable a private integration

Depending on the configuration, integrations can work on a team, site, or both. Once you create and register a private integration, you should be able to find it in the list of integrations available in the Netlify UI.

  1. Log in to the Netlify UI with the credentials for the Netlify team that owns your integration site.
  2. Navigate to the Integrations tab for your team
  3. Select Private to access all private integrations. Your private integration should appear in the list.

Enable on a team

To enable your integration on a team:

  1. Log in to the Netlify UI with the credentials for the Netlify team that owns your integration site.
  2. Navigate to the Integrations tab for your team
  3. Select Private to access all private integrations.
  4. Find your integration and select enable.

Enable on a site

To enable the integration for a site:

  1. In the Netlify UI, navigate to the site you want to edit.
  2. Navigate to the Integrations tab for that site.
  3. Select Private to access all private integrations.
  4. Find your integration and select enable.

Enable on a team and site

For an integration that works on both a team and site level, you first need to enable it on your team level and then enable it on a site level, as mentioned above.

Delete a private integration

To delete a private integration, make sure that it is not enabled on any sites or teams. If the integration is enabled on a site or team, the delete option will not be available.

To delete an integration:

  1. Disable the integration on all teams and sites that have it enabled.
  2. Navigate to the Integrations tab for your team or site in the Netlify UI.
  3. Search for your integration.
  4. Select Delete.

Troubleshooting

Errors when attempting to enable or disable integration

If you encounter an error when enabling or disabling an integration, confirm that the slug in the integration.yaml file within your integration’s source code matches the slug of the integration in the Netlify UI.