StackGuardian Terraform Provider

The StackGuardian Terraform Provider allows Terraform to programmatically interact with the StackGuardian API to help you manage resources on the StackGuardian platform, ultimately enabling organizations to manage cloud infrastructure in a cost-efficient, secure, and compliant way.

It covers 15 resources and 17 data sources — workflows, workflow groups, stacks, templates and their revisions, connectors, policies, roles, role assignments and runner groups.

Tip

Looking for ready-to-use examples? All StackGuardian Terraform modules and examples are maintained in the terraform-stackguardian-modules repository.

Quick start

The provider is published on the Terraform Registry:

terraform {
  required_providers {
    stackguardian = {
      source  = "StackGuardian/stackguardian"
      version = "~> 1.12"
    }
  }
}

provider "stackguardian" {
  api_key  = "<YOUR-API-KEY>"                   # or env var STACKGUARDIAN_API_KEY
  org_name = "<YOUR-ORG-NAME>"                  # or env var STACKGUARDIAN_ORG_NAME
  api_uri  = "https://api.app.stackguardian.io" # or env var STACKGUARDIAN_API_URI; use "https://api.us.stackguardian.io" for the US region
}

resource "stackguardian_workflow_group" "example" {
  resource_name = "Simple-Workflow-Group"
  description   = "Example of how to create a workflow group using the StackGuardian Terraform Provider"
  tags          = ["tf-provider-example", "example"]
}

Documentation

Reference for every resource and data source is on the Terraform Registry, alongside eleven guides:

Guide	What it covers
Installation	Installing and configuring the provider
Getting Started	A working deployment, one resource at a time
Object Model	How workflow groups, templates, connectors and roles relate
Resource IDs	The path-form IDs StackGuardian uses, and where they differ
Runtime References	The ${...} tokens the platform resolves at run time
Templates and Revisions	The template/revision split, and what a revision upgrade changes
Policies	Guardrails, approval gates, and where a policy body comes from
Access Management	Roles, permissions and assignments
Team Onboarding	Laying out groups and roles for a team
Importing Existing Resources	Import ID formats per resource
Troubleshooting	Common errors and what they mean

Examples

• terraform-stackguardian-modules — the collection of StackGuardian Terraform modules and examples.
• Quickstart — a minimal working configuration to get started.
• Onboarding projects — end-to-end projects covering connectors, workflow groups, roles and role assignments.

Development

Prerequisites

• Go 1.21.4 or newer (see go.mod)
• Terraform — CI tests against 1.14.0; the acceptance suite skips versions below 1.1.0, and the import {} block examples need 1.5.0 or newer
• tfplugindocs for documentation work, via make tools-install
• act to run the GitHub workflows locally (optional)

Common tasks

Command	What it does
make build	Compile the provider binary
make install	Build and install into ~/.terraform.d/plugins for local use
make test	Unit tests
make test-acc	Acceptance tests against a real organization
make docs-generate	Regenerate docs/ from the schemas and templates
make docs-validate	Structure and frontmatter checks
make docs-check	Fail if docs/ is out of date — the CI gate
make docs-validate-examples	Type-check every documentation example

Documentation workflow

docs/ is generated — never edit it by hand. Content lives in two places:

• Attribute text comes from MarkdownDescription in each schema.go, mostly via shared constants in internal/constants/. A data source should reuse the same constant as its resource twin so the two cannot drift.
• Page prose lives in docs-templates/, and embedded .tf snippets in docs-examples/.

Edit those, then:

make docs-generate           # rebuild docs/
make docs-validate           # structure and frontmatter
make docs-validate-examples  # type-check every example
make docs-check              # fail if docs/ is stale

docs-validate-examples needs no credentials and makes no API calls. It builds the provider, serves it from a local filesystem mirror, and runs terraform validate over every example — the standalone files under docs-examples/ and docs-guides-assets/, plus every ```terraform block embedded in page and guide prose. Prose blocks are not uniform, so scripts/extract-doc-blocks.py classifies each one and checks it the way it can actually be checked: self-contained snippets are validated, import {} blocks have their target verified against the schema, and bare attribute fragments have their names looked up. That catches unknown resource types, renamed attributes, bad references and type errors before a reader copies them.

Testing

Unit tests need nothing:

make test

Acceptance tests create and destroy real resources, so they need an organization:

export TF_ACC=1
export STACKGUARDIAN_API_KEY=<key>
export STACKGUARDIAN_API_URI=<uri>
export STACKGUARDIAN_ORG_NAME=<org>

make test-acc                                                   # everything
make test-acc TEST=./internal/resource/workflow_git/            # one package
make test-acc TESTARGS='-run TestAccWorkflowGit_WithVcsConfig'  # one test

Every identifier the suite creates is generated per run and prefixed tfacc-, via acctest.ResourceName. Static names made the suite order-dependent: a run that failed before its destroy step left the name taken, and every later run failed at create with 409 already exists. The shared prefix is what makes a leak identifiable afterwards.

When a run is interrupted between create and destroy, its resources survive. Sweep them:

make test-acc-sweep        # report what carries the prefix; deletes nothing
make test-acc-sweep-apply  # delete it

The sweep only ever touches names carrying the tfacc- prefix, and reports rather than deletes unless you ask it to.

Running the workflows locally

The GitHub workflows can be run on your machine with act, which avoids pushing a branch to see a CI result:

make gh-workflow-test-provider     # the provider test workflow
make gh-workflow-test-api-stg      # API tests against staging
make gh-workflow-test-api-prd      # API tests against production

Release notes for each version are in the CHANGELOG and on the GitHub releases page.

Contributing

Contributions are welcome — please see CONTRIBUTING.md for guidelines and the Code of Conduct for community standards. Use GitHub issues to report bugs or request features.

License

This project is licensed under the Mozilla Public License 2.0.