> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rootly.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pulumi

> Manage Rootly resources as infrastructure as code using the official Pulumi provider for Node.js and TypeScript with full support for incident configurations.

## Introduction

The Rootly Pulumi provider lets you manage your Rootly configuration — severities, services, functionalities, on-call schedules, escalation policies, workflows, custom form fields, and more — as infrastructure as code using Pulumi. This allows you to version-control your Rootly configuration, apply changes through CI/CD pipelines, and keep your incident management setup consistent across environments.

The provider is built on top of the [Rootly Terraform provider](/integrations/terraform) and is available on the [Pulumi Registry](https://www.pulumi.com/registry/packages/rootly/installation-configuration/).

<Callout icon="circle-info" color="#DBEAFE">
  The Rootly Pulumi provider currently supports **JavaScript and TypeScript** only. Support for Python, Go, and .NET is not yet available.
</Callout>

## Before You Begin

Before setting up the Pulumi provider, make sure you have:

* [Pulumi CLI](https://www.pulumi.com/docs/install/) installed
* Node.js installed
* A Rootly API token — generate one in **Account** > **Manage API keys** > **Generate New API Key**

## Installation

<Steps>
  <Step title="Install the npm package" icon="download">
    Add the Rootly Pulumi package to your project:

    ```bash theme={null}
    npm install @rootly/pulumi
    ```

    Or with Yarn:

    ```bash theme={null}
    yarn add @rootly/pulumi
    ```
  </Step>

  <Step title="Install the provider plugin" icon="plug">
    Install the Pulumi provider binary:

    ```bash theme={null}
    pulumi plugin install resource rootly v0.0.2 \
      --server https://github.com/rootlyhq/pulumi-rootly/releases/download/v0.0.2
    ```
  </Step>

  <Step title="Configure your API token" icon="key">
    Set your Rootly API token. The recommended approach is to store it as an encrypted Pulumi secret:

    ```bash theme={null}
    pulumi config set rootly:apiToken YOUR_API_TOKEN --secret
    ```

    Alternatively, use an environment variable:

    ```bash theme={null}
    export ROOTLY_API_TOKEN=YOUR_API_TOKEN
    ```

    <Callout icon="triangle-exclamation" color="#FEF3C7">
      Always use `--secret` when setting the API token via `pulumi config` to ensure it is encrypted in your stack state. Never commit an unencrypted API token to version control.
    </Callout>
  </Step>
</Steps>

## Creating Resources

Import the provider and declare resources in your Pulumi program. The following example creates a set of severities, services, functionalities, and a workflow:

```typescript theme={null}
import * as rootly from "@rootly/pulumi";

// Severities
const sev0 = new rootly.Severity("sev0", {
  name: "SEV0",
  color: "#FF0000",
});

const sev1 = new rootly.Severity("sev1", {
  name: "SEV1",
  color: "#FFA500",
});

// Services
const apiService = new rootly.Service("api_service", {
  name: "production-api",
  color: "#800080",
});

// Functionalities
const checkout = new rootly.Functionality("checkout", {
  name: "Checkout",
  color: "#FFFFFF",
});
```

### Supported Resources

The provider supports the full range of Rootly configuration resources, including:

| Category                  | Examples                                                               |
| ------------------------- | ---------------------------------------------------------------------- |
| Incident classification   | `Severity`, `IncidentType`, `IncidentRole`                             |
| Services & infrastructure | `Service`, `Functionality`, `Environment`, `Team`                      |
| On-call                   | `Schedule`, `EscalationPolicy`                                         |
| Workflows                 | `WorkflowIncident`, `WorkflowActionItem`, and 200+ workflow task types |
| Forms & fields            | `FormField`, `FormFieldOption`                                         |
| Status pages              | `StatusPage`, `StatusPageTemplate`                                     |

For the full resource reference, see the [Pulumi Registry documentation](https://www.pulumi.com/registry/packages/rootly/api-docs/).

## Deploying Changes

Preview changes before applying them:

```bash theme={null}
pulumi preview
```

Apply your changes:

```bash theme={null}
pulumi up
```

Pulumi will show a diff of resources to be created, updated, or deleted before prompting for confirmation.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Authentication error: invalid API token" icon="key">
    Confirm your API token is set correctly. If using `pulumi config`, run `pulumi config get rootly:apiToken` to verify the value is present. If using the environment variable, confirm `ROOTLY_API_TOKEN` is exported in your shell. Check that the token has not been revoked in Rootly under **Account > Manage API keys**.
  </Accordion>

  <Accordion title="Provider plugin not found" icon="wrench">
    Run the plugin install command again to ensure the binary is present:

    ```bash theme={null}
    pulumi plugin install resource rootly v0.0.2 \
      --server https://github.com/rootlyhq/pulumi-rootly/releases/download/v0.0.2
    ```

    You can verify installed plugins with `pulumi plugin ls`.
  </Accordion>

  <Accordion title="Resource creation fails with a validation error" icon="triangle-exclamation">
    Check the error message from the Pulumi output — it typically includes the Rootly API response. Common causes include missing required fields (e.g., `name` or `color` on a Severity) or invalid field values. Cross-reference with the [Rootly API reference](/api-reference/overview) for valid field constraints.
  </Accordion>

  <Accordion title="Changes are not reflected in Rootly after pulumi up" icon="rotate">
    Run `pulumi refresh` to reconcile Pulumi's state with the actual state in Rootly. If resources were modified outside of Pulumi (e.g., via the Rootly UI), they may be out of sync with the Pulumi stack state.
  </Accordion>
</AccordionGroup>

## Related Pages

<CardGroup cols={3}>
  <Card title="Terraform" icon="code" href="/integrations/terraform">
    The Rootly Terraform provider — the Pulumi provider is built on top of it.
  </Card>

  <Card title="Rootly API" icon="code" href="/api-reference/overview">
    The Rootly API reference — all resources the provider manages are available here.
  </Card>

  <Card title="Pulumi Registry" icon="arrow-up-right-from-square" href="https://www.pulumi.com/registry/packages/rootly/installation-configuration/">
    Full resource reference and API docs on the Pulumi Registry.
  </Card>
</CardGroup>