terraform-provider-stackgen

sg_guild_integration (Resource)

⚠️ Experimental — This resource is part of the Guild platform and may change in future releases.

Manages a guild-level integration connecting agents to an external system (e.g. MCP servers, Salesforce, Jira). Integrations are registered at the guild level and can be attached to one or more agents. Import by integration name; import requires Guild GET to return its configuration and ID.

Example Usage

# When to use: Register a tool integration (MCP, Grafana, Jira, AWS, …) that
# agents and knowledge sources can attach by name. Create secrets / credential
# providers first when the integration needs credentials.
#
# Prerequisites: optional sg_secret IDs (secret_ref_ids) or
# sg_credential_provider (credential_provider_id) for OAuth.
#
# Related: sg_agent.integrations, sg_knowledge_source.integration_name,
# sg_app.integrations (SRE app bindings), data.sg_guild_integration (lookup).
#
# MCP-style integration — add secret_ref_ids when the integration needs static credentials.
resource "sg_guild_integration" "example" {
  name        = "prod-github-mcp"
  description = "GitHub MCP server for repository automation."
  type        = "mcp"
  enabled     = true
}

# When to use: Prefer this over static secret_ref_ids when the vendor supports
# 3-legged OAuth (GitHub App, Salesforce, …). Create sg_credential_provider first.
#
# Integration using a 3-legged OAuth credential provider (see sg_credential_provider).
resource "sg_guild_integration" "oauth_example" {
  name                   = "github-app-integration"
  description            = "Uses dynamic OAuth tokens from a credential provider."
  type                   = "mcp"
  enabled                = true
  credential_provider_id = "00000000-0000-4000-8000-000000000002" # replace with sg_credential_provider.*.id
}

Import

Import an existing sg_guild_integration using its integration name:

terraform import sg_guild_integration.example 'example-grafana'

Operational notes

Create always checks the scoped integration name before upsert. If the name exists, strict mode fails; with adoption enabled only matching configured fields can be adopted without writing. A concurrent create between GET and upsert still requires backend conditional-create support. secret_ref_ids links Vault secrets; credential_provider_id links an OAuth credential provider. Provision credentials first. Integration env and secret references may expose sensitive connection metadata in Terraform state; secure state and plans.

Schema

Required

description (String) Description of the integration.
enabled (Boolean) Whether this integration is active. Disabled integrations do not provide tools.
name (String) Unique integration identifier (e.g. prod-github-mcp). Changing forces replacement.
type (String) Integration type (e.g. mcp or salesforce or jira).

Optional

credential_provider_id (String) UUID of a Vault Credential Provider for dynamic 3-legged OAuth tokens.
env (Map of String) Environment variables injected into containerized integration containers at launch.
id (String) Server-assigned UUID for this integration (from Guild API).
image (Attributes) OCI container image configuration for containerized integration types. (see below for nested schema)
runner_id (String) Remote runner UUID to execute connection tests and agent tool calls. Omit to retain the binding; an explicit empty string clears it.
scope (String) Integration scope: TENANT PROJECT or USER. Defaults to PROJECT when omitted so create does not send an empty scope enum.,default_string:PROJECT
secret_ref_ids (List of String, Sensitive) UUIDs of Vault secrets holding connection credentials. All secrets are merged in order.

Nested Schema for `image`

Optional:

name (String) Container image name (e.g. registry.local/ocr-agent:v1.2).
registry_credentials_secret (String) Vault secret reference for registry credentials.