---
url: https://docs.puppetflow.com/guide/integrations.md
---
# Integrations

Integrations connect Puppetflow to external services.

## Workflow automation

### n8n

The [`n8n-nodes-puppetflow`](https://www.npmjs.com/package/n8n-nodes-puppetflow) community node adds Puppetflow browser automation to n8n workflows. It can:

* Trigger a flow with optional JSON input.
* List runs and filter them by status.
* Retrieve a run and its result.
* List and download screenshots or downloaded files.
* Download session recordings.

#### Install the node

Installing a community package from npm requires a self-hosted n8n instance.

1. In n8n, open **Settings > Community Nodes**.
2. Click **Install** and enter `n8n-nodes-puppetflow`.
3. Add a **Puppetflow** node to a workflow.
4. Create a **Puppetflow API** credential.
5. Enter the root URL of your Puppetflow instance, without `/api/v1`.
6. In Puppetflow, open **Profile > API Keys**, generate a key, and enter it in the n8n credential.

See the [n8n community node installation guide](https://docs.n8n.io/integrations/community-nodes/installation/) for alternative installation methods.

## AI integrations&#x20;

Puppetflow supports OpenAI, Google Gemini, Anthropic Claude, and Mistral. An AI integration stores the API key and discovers the AI models available to that account.

1. Go to **Integrations** and choose the AI integration.
2. Enter a name and select personal, team, or workspace visibility.
3. Enter the API key.
4. Validate the connection, then click **Connect**.

The API key is stored in the integration and is never added to flow code. Editing an integration with an empty API key keeps the existing key.

After connecting an AI integration, select the [AI models](/guide/flows#ai-models) that flows may use.

## Repository integrations

Link your flows to Git repositories so the code stays in sync with your codebase.

### GitHub

GitHub integration uses a GitHub App for secure access. Setup:

1. Go to **Integrations** and click **GitHub**.
2. Puppetflow generates an App manifest and redirects you to GitHub to create the App.
3. Install the App on your repositories.
4. Back in Puppetflow, the integration is active and you can link flows to files.

Once connected, you can:

* Browse repositories and branches.
* Link a flow to a specific file path.
* Choose a sync trigger (`push` or `tag`).
* Code updates automatically when the event fires.

Git repositories are also used by the blueprints system. Public blueprints are read from the configured repository. Private blueprints can use additional repositories when this option is enabled for the instance.

### Private libraries and blueprints

Private libraries are workspace-level blueprint sources configured under **Workspace > Settings > Private Libraries**.

Use private blueprints when you want to distribute internal blueprints without publishing them to the public store. They support:

* owner, workspace, or team visibility,
* branch selection,
* manual refresh,
* grouping,
* importing flows and snippets into the workspace,
* update notifications.

Enter a public **GitHub URL** in `https://github.com/<owner>/<repo>` format. Puppetflow reads the repository anonymously through GitHub, so private repositories are not supported here.

### Other providers

GitLab, Bitbucket, and Gitea are listed as available providers in the integration settings.

## Vault integrations

### 1Password

On Pro and above, connect to 1Password for runtime secret resolution.

#### Run 1Password Connect

Create a Connect server in 1Password, then place the generated `1password-credentials.json` file next to your Puppetflow Docker Compose file.

Add these services to the Puppetflow Compose configuration:

```yaml
services:
  op-connect-api:
    image: 1password/connect-api:1.8.1
    restart: unless-stopped
    volumes:
      - "./1password-credentials.json:/home/opuser/.op/1password-credentials.json:ro"
      - "onepassword-data:/home/opuser/.op/data"
    networks:
      - puppetflow

  op-connect-sync:
    image: 1password/connect-sync:1.8.1
    restart: unless-stopped
    volumes:
      - "./1password-credentials.json:/home/opuser/.op/1password-credentials.json:ro"
      - "onepassword-data:/home/opuser/.op/data"
    networks:
      - puppetflow

volumes:
  onepassword-data:
```

Start both services:

```bash
docker compose up -d op-connect-api op-connect-sync
```

The Connect access token is used by Puppetflow to authenticate with the API. It does not need to be passed to the Connect containers.

#### Connect Puppetflow

1. Go to **Integrations** and click **1Password**.
2. Set **Connect Server URL** to `http://op-connect-api:8080`.
3. Enter the 1Password **Connect Token**.
4. Browse vaults, items, and fields.

Once connected:

* Create **Vault** variables that reference specific 1Password fields.
* Values are fetched at runtime, never stored in Puppetflow.
* OTP fields from 1Password generate fresh TOTP codes.

## Messenger integrations

Connect chat platforms for notifications and human approval gates.

### Telegram

1. Create a Telegram bot via [@BotFather](https://t.me/BotFather).
2. Enter the bot token in the integration settings.
3. Puppetflow detects available chats.
4. Create notification channels from the detected chats.

### Discord

1. Create a Discord bot in the Developer Portal.
2. Enter the bot token.
3. Puppetflow detects available channels.

### Slack

1. Create a Slack app with a bot token.
2. Enter the token.
3. Puppetflow detects available channels.

## Mailbox integration

The mailbox integration manages custom email domains for receiving emails.

1. Go to **Integrations** and click **Mailbox**.
2. Add a domain name.
3. Configure the A, MX, and TXT records shown by Puppetflow.
4. Verify the domain.

Once verified, you can create mailboxes on that domain and use them in flow [mailbox watchers](/guide/mailboxes).

### DNS setup

Puppetflow provides the exact DNS records to add:

* **A record** - `mail.<domain>` points to the Puppetflow server's public IP.
* **MX record** - `<domain>` points to `mail.<domain>` with priority 10.
* **TXT record** - `v=spf1 mx ~all`.

The domain detail page shows a DNS verification checker that validates your records in real time.

## Managing integrations

All integrations support:

* **Visibility** - Owner, Team, or Workspace.
* **Active toggle** - Disable an integration without deleting it.
* **Usage tracking** - See which flows and variables reference the integration before deleting.
