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:
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:
| Argument | Environment variable | Description |
|---|---|---|
api_key | POSTHOG_API_KEY | Your personal API key. Required. |
host | POSTHOG_HOST | The 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_id | POSTHOG_PROJECT_ID | The project that project-level resources, such as feature flags and insights, belong to. Each resource can override it with its own project_id. |
organization_id | POSTHOG_ORGANIZATION_ID | The 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:
- 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.
- Copy your project ID from Settings > Project > General.
- 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:
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.
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:
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.
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:
You can also import from the command line:
The import ID depends on the resource:
- Project-level resources use
<project_id>/<resource_id>, for example12345/678. If the provider setsproject_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:
Flags that already exist are imported, and the rest are created.
Resources and data sources
The provider includes these resources:
| Resource | Manages |
|---|---|
posthog_access_control | Access rules for a resource type or a single resource |
posthog_action | Actions |
posthog_alert | Alerts on insights |
posthog_cohort | Cohorts |
posthog_dashboard | Dashboards |
posthog_dashboard_layout | The tiles on a dashboard and where they sit |
posthog_early_access_feature | Early access features |
posthog_experiment | Experiments |
posthog_external_data_source | Data Warehouse sources, such as Stripe or Postgres |
posthog_feature_flag | Feature flags |
posthog_hog_function | Destinations, transformations, and webhooks |
posthog_insight | Insights |
posthog_insight_variable | SQL variables |
posthog_logs_alert | Log alerts |
posthog_logs_alert_destination | Where a log alert sends notifications |
posthog_organization_member | Organization members |
posthog_project | Projects |
posthog_project_default_access | A project's default access level |
posthog_project_member | A role's or member's access to a project |
posthog_project_settings | Project settings |
posthog_proxy_record | Managed reverse proxy domains |
posthog_role | Roles |
posthog_role_membership | Role members |
posthog_subscription | Dashboard and insight subscriptions |
posthog_survey | Surveys |
posthog_warehouse_table | Data Warehouse tables backed by files in your own bucket |
It also includes these data sources:
| Data source | Looks up |
|---|---|
posthog_feature_flags | The feature flags in a project |
posthog_insight | An insight, by the short ID in its URL |
posthog_role | A role, by name |
posthog_user | An 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.





