diff --git a/content/docs/ai/_index.md b/content/docs/ai/_index.md index d3e30d99d6c6..f3c32f986e48 100644 --- a/content/docs/ai/_index.md +++ b/content/docs/ai/_index.md @@ -51,6 +51,10 @@ sections: heading: Previews link: /docs/ai/running-previews/ description: Generate infrastructure previews with approval gates. + - emoji: 🔌 + heading: Integrations + link: /docs/ai/integrations/ + description: Connect Neo to third-party services like Datadog, Honeycomb, and Linear. - type: flat heading: Have questions? diff --git a/content/docs/ai/integrations/_index.md b/content/docs/ai/integrations/_index.md new file mode 100644 index 000000000000..3e7e4db34539 --- /dev/null +++ b/content/docs/ai/integrations/_index.md @@ -0,0 +1,117 @@ +--- +title: Integrations +title_tag: Neo Integrations +h1: Neo Integrations +meta_desc: Bring context from issue trackers, observability platforms, and wikis into Neo tasks so it can act on what your team already knows. +meta_image: /images/docs/meta-images/docs-meta.png +menu: + ai: + name: Integrations + parent: ai-home + weight: 55 + identifier: ai-integrations +--- + +Neo integrations bring context from your existing tools into infrastructure tasks. Neo can read directly from the services your team already uses, such as issue trackers, observability platforms, wikis, and databases, and apply that context to infrastructure tasks. + +Integrations are configured at the organization level by an administrator. Once enabled, they are available to all tasks in the organization. + +## What you can do with integrations + +- **Pick up work from your issue tracker.** Connect Linear or Jira and ask Neo to implement an issue. Neo reads the issue description, acceptance criteria, and comments, then writes the infrastructure changes to match. +- **Follow your runbooks.** Connect Confluence and point Neo at an operational runbook. Neo follows the documented steps, adapting them to your current environment. +- **Investigate with real observability data.** Connect Honeycomb or Datadog and ask Neo to diagnose a performance problem. Neo queries actual traces and metrics from your environment to narrow down the cause. +- **Respond to incidents.** Connect PagerDuty and let Neo look up active incidents, on-call schedules, and escalation policies while it investigates. +- **Manage application infrastructure together.** Connect Supabase and let Neo coordinate database changes alongside your Pulumi infrastructure code. + +## Enabling an integration + +To enable an integration, navigate to **Neo Settings**, select **Integrations**, select the integration, and provide the required credentials. + +Each integration connects Neo to the service's [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server, which means Neo can use the full set of tools that service exposes through MCP. + +### Credential storage + +Integration credentials are encrypted at rest in the Pulumi Service using a per-organization encryption key. When a task needs to connect to an integration, the service decrypts the credentials at task time, constructs the appropriate authentication headers, and connects to the service on Neo's behalf. Credentials are never exposed to the language model and are never embedded in task state. + +## Disabling an integration + +To remove an integration from your organization, navigate to **Neo Settings**, select **Integrations**, find the integration, and select **Remove**. + +Disabling an integration deletes its stored credentials and immediately prevents any new tasks from using it. Tasks that are already running will lose access to the integration on their next tool call. + +## How integrations work at task time + +When Neo starts a task, it connects to each enabled integration's MCP server using the stored credentials. From there, Neo can use any tools the MCP server provides. For example, with the Honeycomb integration enabled, Neo can query traces to investigate a performance issue that came up during an infrastructure review. With Linear enabled, Neo can look up the details of an issue referenced in a task description. + +The integration connection is transparent. Neo decides when to use an integration based on the context of your conversation, just as it decides when to use any other tool. + +## Per-task control + +By default, every task inherits all integrations the organization has enabled. If you want to narrow Neo's focus for a specific task — for example, running a deployment review without giving Neo access to your issue tracker — you can toggle individual integrations off from the task composer before starting the conversation. The toggles only affect the current task; the org-level configuration is unchanged. + +## If an integration fails + +Integrations are resolved independently at the start of each message. If credentials for one integration can't be retrieved, or its MCP server is unreachable, Neo logs a warning, skips that integration, and continues the task with the remaining ones. A single broken integration won't stop a task from running. + +If Neo tries to use an integration that isn't available — for example, because the credentials were removed or expired — it will surface the failure in the conversation and continue with its other tools. + +## Configuration + +### Atlassian (Jira & Confluence) + +1. In **admin.atlassian.com**, open **Rovo MCP** + - Enable **API token authentication** + - Add `https://*.pulumi.com/**` as an allowed domain +1. Open **Directory**, then **Service Accounts** +1. Create a service account and give it user access to each product you want Neo to access +1. Create a credential for the service account with type **API** and assign the necessary roles +1. In Neo, enter the **Service Account API Token** and your **Site URL** (e.g., `https://yoursite.atlassian.net`) + +### Datadog + +1. In **Organization Settings**, open **Service Accounts** and create a service account with read-only access +1. On the service account's details page, create an **App Key** and make sure to include the MCP read scope +1. In **Organization Settings**, open **API Keys** and create an **API Key** +1. Identify your Datadog site — it's the domain you use to access Datadog (for example, `datadoghq.com` is `us1`, `datadoghq.eu` is `eu1`). Supported codes: `us1`, `us3`, `us5`, `eu1`, `ap1`, `ap2`. +1. In Neo, enter the **Datadog site** code, **API Key**, and **App Key** + +### Honeycomb + +1. In Honeycomb, navigate to **Account**, then **Team Settings**, then **API Keys** +1. Select **Create Management API Key** and give it a name (e.g., "MCP Integration") +1. Choose the **Model Context Protocol** and **Environments** scopes, then grant permissions: + - **Read**: Required for all Honeycomb MCP operations. Make sure to grant read for both MCP and Environments. + - **Write**: Required for the `create_board` tool. +1. Copy the **Key ID** and **Key Secret**. You will not be able to see them again. +1. In Neo, enter the **Key ID** and **Key Secret** in the corresponding fields + +### Linear + +{{% notes type="info" %}} +Linear API keys are personal tokens. All actions Neo takes through this integration are attributed to the user who created the token, regardless of who creates the Neo task. OAuth support is planned for a future release. +{{% /notes %}} + +1. In Linear, open **Settings**, then **Security & Access** +1. Select **New API Key**, give it a name, and configure the permissions and team access for your use case +1. In Neo, enter the **API Key** + +### PagerDuty + +{{% notes type="info" %}} +PagerDuty User API Tokens are tied to a single user account. All actions Neo takes through this integration are attributed to the user who created the token, regardless of who creates the Neo task. For shared use, consider creating a dedicated PagerDuty user (e.g. `pulumi-bot`) whose token Neo can use. +{{% /notes %}} + +1. In PagerDuty, open your user profile and select **User Settings** +1. Select **Create API User Token**, give it a name (e.g., "Neo Integration"), and copy the token +1. In Neo, enter the **User API Token** + +### Supabase + +{{% notes type="info" %}} +Supabase Access Tokens are tied to a single user account — Supabase does not offer service-account credentials for the MCP server. All actions Neo takes through this integration are attributed to the user who created the token, regardless of who creates the Neo task. For shared use, consider creating a dedicated Supabase user (e.g. `pulumi-bot`) whose token Neo can use. +{{% /notes %}} + +1. On **supabase.com**, open **Account Preferences**, then **Access Tokens** +1. Select **Generate New Token**, give it a name, and copy the token +1. In Neo, enter the **Access Token** diff --git a/content/docs/ai/settings/_index.md b/content/docs/ai/settings/_index.md index 726a83f7273a..00722b9b37f2 100644 --- a/content/docs/ai/settings/_index.md +++ b/content/docs/ai/settings/_index.md @@ -2,7 +2,7 @@ title: Settings title_tag: Neo Settings h1: Neo Settings -meta_desc: Configure Neo for your organization with Custom Instructions, Repository Instructions (AGENTS.md), Slash Commands, access controls, and task modes. +meta_desc: Configure Neo with Custom Instructions, Repository Instructions, Slash Commands, integrations, access controls, and task modes. meta_image: /images/docs/meta-images/docs-meta.png menu: ai: @@ -144,6 +144,12 @@ You can place `AGENTS.md` files in subdirectories for more specific instructions - Keep instructions actionable and specific - Review and update as your project's practices evolve +## Integrations + +Neo can connect to third-party services like issue trackers, observability platforms, and wikis, giving tasks the ability to query external tools alongside your infrastructure. Integrations are configured in the **Integrations** tab of Neo Settings, where administrators can enable services and provide credentials. + +See [Integrations](/docs/ai/integrations/) for the full list of available integrations, setup instructions, and credential storage details. + ## Slash commands Slash Commands capture proven prompts as shortcuts that anyone on your team can use. When you type `/` in a Neo conversation, you'll see available commands. Selecting a command sends the full prompt to Neo. diff --git a/content/docs/ai/tasks/_index.md b/content/docs/ai/tasks/_index.md index c58c443545d8..d03cb840c20a 100644 --- a/content/docs/ai/tasks/_index.md +++ b/content/docs/ai/tasks/_index.md @@ -71,6 +71,10 @@ At any time, you can ask Neo to run a [pulumi preview](/docs/iac/cli/commands/pu If a task results in code modifications, Neo will offer to open a [pull request](/docs/ai/pull-requests/) once you are satisfied with the implementation. PRs can also be modified after they have been opened. +## Integrations + +If your organization has [integrations](/docs/ai/integrations/) enabled, Neo can read from external services like issue trackers, observability platforms, and runbooks during tasks. + ## Context, sharing, and history ### Setting entity context