Provider

The provider manages a workspace's configuration through the resource API. Each resource maps to one API kind, and its attributes are the kind's fields in snake case, as passesTo is passes_to. The fields are described on each kind's page, which names any other difference; the provider's own generated documentation lists every attribute.

SourceCopy Anchor Link

terraform {
  required_providers {
    spotlight = {
      source = "usespotlightai/spotlight"
    }
  }
}

Provider configurationCopy Anchor Link

• A token and a trust are exclusive. With both, configuration fails with Both a token and an OIDC trust.
• url and token must be known when Terraform plans.
• A token minted through a trust is renewed one minute before it expires, and exchanged again when Spotlight refuses it with 401.
• In GitHub Actions, the job needs permissions: id-token: write; the provider reads ACTIONS_ID_TOKEN_REQUEST_URL and ACTIONS_ID_TOKEN_REQUEST_TOKEN to request the OIDC token.
• Every request carries Spotlight-Client: terraform-provider/<version> and Spotlight-Api-Version.
• GET requests, and requests that carry an Idempotency-Key, are retried up to 3 times after a network error or a 429, 502, 503 or 504 response, waiting 500 milliseconds before the first retry and doubling each time.

Terraform versionsCopy Anchor Link

ResourcesCopy Anchor Link

There is no resource for workspace tokens.

spotlight_hook, its list resource, its write-only signing.secret_wo and the plan-time checks of hook expressions require a provider release that includes them.

Every resource has these read-only attributes: id, version and address, as the common fields describe. Every resource has a resource identity, { id = "<id>" }, which an import block may name instead of the import id:

import {
  to = spotlight_line.core_delivery
  identity = {
    id = "<line id>"
  }
}

spotlight_workspace is imported, never created. See In Terraform.

Warnings the API returns become Terraform warnings on the attribute they name.

Data sourcesCopy Anchor Link

List resourcesCopy Anchor Link

Each resource has a list resource of the same name, used in a list block in a .tfquery.hcl file.

list "spotlight_line" "core" {
  provider = spotlight
  config {
    workspace_id = "<workspace id>"
    team_id      = "<team id>"
  }
}

terraform query -generate-config-out=generated.tf writes a resource and an import block for each item. Prompts and skill files are written inline.

ReplacementCopy Anchor Link

Changing any of these attributes replaces the resource.

Write-only valuesCopy Anchor Link

Write-only attributes are sent to Spotlight and never stored in the plan or the state. Each has a version attribute beside it; a change to the version sends the value again.

A pull pool created without token is issued one by Spotlight in the Spotlight-Pool-Token response header. The provider does not keep it, and warns.

Plan-time expression checksCopy Anchor Link

During terraform plan, the provider sends each CEL expression in a spotlight_integration definition and in a spotlight_hook (when and the templated strings in steps) to POST /api/expressions/check. An expression that does not check fails the plan, on the attribute that holds it. The token needs the plan scope.

In HCL, an expression in an integration's definition or a hook's steps is written $${{ ... }}, Terraform's escape for a literal ${{ ... }}. A hook's when may be written bare, without ${{ }}.

See Expressions for what each position sees.