Linking Spacelift as a source

Alpha release

This source is currently in alpha. The interface and available tables may change.

The Spacelift connector syncs your infrastructure-as-code data into PostHog, including stacks, runs, policies, and managed resources. Use it to analyze deployment frequency, run durations, drift detection, and policy activity across your Terraform, OpenTofu, and Pulumi stacks.

Prerequisites

You need a Spacelift account and permission to create API keys (found under Organization settings in Spacelift). The API key needs read access to the spaces containing the data you want to sync.

Adding a data source

In PostHog, go to the Sources tab of the data pipeline section.
Click + New source and click Link next to this source.
Enter your credentials (see Configuration below) and click Next.
Select the tables you want to sync, choose a sync method and frequency, then click Import.

Once the syncs are complete, you can start querying this data in PostHog.

To connect Spacelift, you need three values:

Account name: the subdomain you use to access Spacelift. For example, if your Spacelift URL is my-company.app.spacelift.io, the account name is my-company.
API key ID and API key secret: in Spacelift, go to Organization settings → API keys and create a new API key with read access to the spaces you want to sync. Spacelift shows the key ID in the UI and provides the secret in a downloadable file when the key is created.

PostHog exchanges the key ID and secret for a short-lived token on each sync, so the secret is only ever sent to your own Spacelift account's API endpoint.

Sync modes

Each table can be synced in one of several modes, depending on what the source supports:

Webhook (when available) – the source pushes changes to PostHog in real time. Fastest freshness, lowest ongoing cost, and the only mode that reliably captures updates and deletes.
Incremental – only new or updated rows are synced on each run, using a cursor field (such as an updated_at timestamp). Cheaper than a full refresh, but deletes aren't captured.
Append only – new rows are appended using a cursor field; existing rows are never updated. Ideal for immutable, append-only tables like event logs.
Full refresh – the whole table is reloaded on every sync. Use it when a table has no reliable cursor or when you need deletions reflected.

See sync methods for a full explanation of how each mode works and how to choose between them.

The runs table supports incremental syncs on the createdAt field (a Unix timestamp in seconds). Because runs can change state after they're created, each incremental sync re-pulls the last 7 days of runs and merges them, so recent runs converge on their final state. All other tables are small configuration catalogs and sync as full refreshes.

Configuration

Option	Type	Required
`Account name`	text	Yes
`API key ID`	text	Yes
`API key secret`	password	Yes

Supported tables

Table	Description	Sync method	Incremental field	Primary key
`stacks`	Infrastructure-as-code stacks: the core unit tying a VCS repository to Terraform/OpenTofu/Pulumi state, with current status and drift information.	Full refresh	—	—
`runs`	All runs across every stack and module. Incremental syncs re-pull the last 7 days so state changes on recent runs are captured	Incremental, Full refresh	createdAt	—
`policies`	Open Policy Agent (Rego) policies controlling login, access, approval, push, and notification behavior across the account.	Full refresh	—	—
`contexts`	Reusable bundles of environment variables and mounted files attached to stacks.	Full refresh	—	—
`modules`	Terraform modules published to the Spacelift module registry, with their tracked repository and current version.	Full refresh	—	—
`worker_pools`	Private worker pools that execute runs, with queue depth and busy-worker counts.	Full refresh	—	—
`spaces`	Organizational spaces grouping stacks, policies, and other resources into an access-control hierarchy.	Full refresh	—	—
`managed_entities`	Terraform/OpenTofu resources managed across your stacks, including drift status	Full refresh	—	—

Troubleshooting

"Invalid Spacelift API key": the key ID or secret is wrong, or the key was deleted. Create a new API key in your Spacelift organization settings and reconnect.
"Spacelift API returned unauthorized": the key is valid but lacks access to the requested data. Grant the key read access to the relevant spaces in Spacelift.
"Invalid Spacelift account name": enter only the subdomain of your Spacelift URL (e.g. my-company, not my-company.app.spacelift.io or a full URL).

If your sync is failing or data looks wrong, see the Data warehouse troubleshooting guide. If that doesn't help, contact support – we're happy to help.