Terraform provider

Contents

The PostHog Terraform provider lets you manage PostHog resources, such as feature flags, insights, dashboards, alerts, and access rules, as Terraform code. You can review changes in pull requests, apply them from your CI/CD pipeline, and set up several projects the same way from one configuration.

The provider is published to the Terraform Registry as PostHog/posthog and is open source on GitHub. It needs Terraform 1.0 or later.

Install the provider

Add the provider to your Terraform configuration:

hcl
terraform {
required_providers {
posthog = {
source = "PostHog/posthog"
version = "~> 1.0"
}
}
}

Then run terraform init to download it.

The ~> 1.0 constraint accepts any release in major version 1. The Terraform Registry lists the latest version, and the changelog lists what changed in each one.

Authenticate

The provider calls the PostHog API with a personal API key. You can set each of its arguments in the provider block or with an environment variable:

ArgumentEnvironment variableDescription
api_keyPOSTHOG_API_KEYYour personal API key. Required.
hostPOSTHOG_HOSTThe PostHog URL to call. Defaults to https://us.posthog.com. Use https://eu.posthog.com for EU Cloud, or your instance's URL if you self-host.
project_idPOSTHOG_PROJECT_IDThe project that project-level resources, such as feature flags and insights, belong to. Each resource can override it with its own project_id.
organization_idPOSTHOG_ORGANIZATION_IDThe organization that organization-level resources, such as projects, members, roles, and proxy records, belong to. Accepts the organization's UUID or slug. Each resource can override it with its own organization_id.

To set up authentication:

  1. Create a personal API key. Give it the scopes for the resource types you manage, and limit it to the organization or projects your configuration covers.
  2. Copy your project ID from Settings > Project > General.
  3. If you manage organization-level resources, copy your organization ID from Settings > Organization > General.

Keep the API key out of your configuration files. Pass it as an environment variable and set the other arguments in the provider block:

Terminal
export POSTHOG_API_KEY="<your-personal-api-key>"
hcl
provider "posthog" {
host = "https://eu.posthog.com"
project_id = "12345"
organization_id = "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b"
}

Examples

Roll out a feature flag

This flag is on for 25% of users. Change rollout_percentage and apply again to roll it out further.

hcl
resource "posthog_feature_flag" "new_onboarding" {
key = "new-onboarding"
name = "New onboarding flow"
rollout_percentage = 25
tags = ["managed-by:terraform"]
}

For multivariate flags, payloads, and release conditions, set filters. See the posthog_feature_flag reference for every attribute.

Add an insight to a dashboard

This creates a dashboard and a trends insight that counts pageviews, and places the insight on the dashboard:

hcl
resource "posthog_dashboard" "growth" {
name = "Growth"
description = "Weekly growth metrics"
tags = ["managed-by:terraform"]
}
resource "posthog_insight" "pageviews" {
name = "Pageviews"
dashboard_ids = [posthog_dashboard.growth.id]
query_json = jsonencode({
kind = "InsightVizNode"
source = {
kind = "TrendsQuery"
series = [{
kind = "EventsNode"
event = "$pageview"
math = "total"
}]
}
})
}

To write the insight in SQL instead, replace query_json with query_sql. To control where each tile sits on the dashboard, see managing dashboards with Terraform.

Send an alert to a webhook

An alert checks an insight on a schedule and fires when its value crosses a threshold. To deliver the alert, add a destination: a posthog_hog_function that listens for the $insight_alert_firing event of that alert.

hcl
resource "posthog_alert" "pageview_spike" {
name = "Pageview spike"
insight = posthog_insight.pageviews.id
subscribed_users = []
condition_type = "absolute_value"
threshold_type = "absolute"
threshold_upper = 10000
series_index = 0
calculation_interval = "daily"
}
resource "posthog_hog_function" "pageview_spike_webhook" {
name = "Pageview spike webhook"
type = "internal_destination"
template_id = "template-webhook"
filters_json = jsonencode({
events = [{
id = "$insight_alert_firing"
type = "events"
}]
properties = [{
key = "alert_id"
value = posthog_alert.pageview_spike.id
operator = "exact"
type = "event"
}]
})
inputs_json = jsonencode({
url = {
value = "https://example.com/hooks/posthog-alert"
}
method = {
value = "POST"
}
body = {
value = {
alert_name = "{event.properties.alert_name}"
value = "{event.properties.alert_calculated_value}"
}
templating = "hog"
}
})
}

To post to Slack instead, use template_id = "template-slack". The provider repository has a full Slack example.

Manage existing resources

You don't have to recreate resources that already exist in PostHog. There are three ways to bring them under Terraform.

Export from the PostHog app

Dashboards, insights, and the project's access control settings have a Manage with Terraform button. It generates a configuration for the resource and related resources, such as a dashboard's insights and alerts, with import blocks so that Terraform adopts them instead of creating copies. Copy it into your configuration and run terraform apply.

Write import blocks

An import block (Terraform 1.5 or later) adopts an existing resource on the next apply:

hcl
import {
to = posthog_feature_flag.new_onboarding
id = "12345/678"
}

You can also import from the command line:

Terminal
terraform import posthog_feature_flag.new_onboarding 12345/678

The import ID depends on the resource:

  • Project-level resources use <project_id>/<resource_id>, for example 12345/678. If the provider sets project_id, the resource ID on its own works too.
  • Organization-level resources use <organization_id>/<resource_id>. A project's import ID always includes the organization ID.

Each resource's page in the registry docs shows its import ID format.

Adopt many feature flags at once

The posthog_feature_flags data source lists a project's flags, so a for_each import block (Terraform 1.7 or later) can adopt every flag your configuration declares without you looking up flag IDs:

hcl
locals {
feature_flags = {
"new-onboarding" = { name = "New onboarding flow", rollout = 25 }
"beta-dashboard" = { name = "Beta dashboard", rollout = 0 }
}
}
data "posthog_feature_flags" "existing" {}
resource "posthog_feature_flag" "this" {
for_each = local.feature_flags
key = each.key
name = each.value.name
rollout_percentage = each.value.rollout
}
import {
for_each = {
for flag in data.posthog_feature_flags.existing.flags : flag.key => flag.id
if contains(keys(local.feature_flags), flag.key)
}
to = posthog_feature_flag.this[each.key]
id = "${data.posthog_feature_flags.existing.project_id}/${each.value}"
}

Flags that already exist are imported, and the rest are created.

Resources and data sources

The provider includes these resources:

ResourceManages
posthog_access_controlAccess rules for a resource type or a single resource
posthog_actionActions
posthog_alertAlerts on insights
posthog_cohortCohorts
posthog_dashboardDashboards
posthog_dashboard_layoutThe tiles on a dashboard and where they sit
posthog_early_access_featureEarly access features
posthog_experimentExperiments
posthog_external_data_sourceData Warehouse sources, such as Stripe or Postgres
posthog_feature_flagFeature flags
posthog_hog_functionDestinations, transformations, and webhooks
posthog_insightInsights
posthog_insight_variableSQL variables
posthog_logs_alertLog alerts
posthog_logs_alert_destinationWhere a log alert sends notifications
posthog_organization_memberOrganization members
posthog_projectProjects
posthog_project_default_accessA project's default access level
posthog_project_memberA role's or member's access to a project
posthog_project_settingsProject settings
posthog_proxy_recordManaged reverse proxy domains
posthog_roleRoles
posthog_role_membershipRole members
posthog_subscriptionDashboard and insight subscriptions
posthog_surveySurveys
posthog_warehouse_tableData Warehouse tables backed by files in your own bucket

It also includes these data sources:

Data sourceLooks up
posthog_feature_flagsThe feature flags in a project
posthog_insightAn insight, by the short ID in its URL
posthog_roleA role, by name
posthog_userAn organization member, by email

Upgrading

To move to a newer release, raise the version constraint if needed and run terraform init -upgrade. Before you upgrade, read the changelog for breaking changes and upgrade notes, and run terraform plan to check the changes before you apply them.

Still have questions?

Was this page useful?