create_run

create_run

Initiate infrastructure changes using Terraform Cloud by creating a run in a specified workspace. This tool triggers plan and apply operations for deploying, updating, or destroying resources based on workspace settings.

Instructions

Create a run in a workspace

Creates a new Terraform run to trigger infrastructure changes through Terraform Cloud, representing a single execution of plan and apply operations. The run queues in the workspace and executes based on the workspace's execution mode and settings. Use this to deploy new infrastructure, apply configuration changes, or destroy resources.

API endpoint: POST /runs

Args: workspace_id: The workspace ID to execute the run in (format: "ws-xxxxxxxx") params: Optional run configuration with: - message: Description of the run's purpose - is_destroy: Whether to destroy all resources managed by the workspace - auto_apply: Whether to auto-apply after a successful plan - refresh: Whether to refresh Terraform state before planning - refresh_only: Only refresh the state without planning changes - plan_only: Create a speculative plan without applying - allow_empty_apply: Allow applying when there are no changes - target_addrs: List of resource addresses to specifically target - replace_addrs: List of resource addresses to force replacement - variables: Run-specific variables that override workspace variables - terraform_version: Specific Terraform version to use for this run - save_plan: Save the plan for later execution - debugging_mode: Enable extended debug logging

Returns: The created run details with ID, status, configuration information, workspace relationship, and links to associated resources

See: docs/tools/run.md for reference documentation

Input Schema

Name	Required	Description	Default
`params`	No
`workspace_id`	Yes

Input Schema (JSON Schema)

{
  "$defs": {
    "RunParams": {
      "description": "Parameters for run operations without routing fields.\n\nThis model provides all optional parameters that can be used when creating runs,\nreusing the field definitions from BaseRunRequest.\n\nReference: https://developer.hashicorp.com/terraform/cloud-docs/api-docs/run#create-a-run\n\nNote:\n    All fields are inherited from BaseRunRequest.\n\nSee:\n    docs/models/run.md for reference",
      "properties": {
        "allow-config-generation": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": false,
          "description": "Whether to allow generating config for imports",
          "title": "Allow-Config-Generation"
        },
        "allow-empty-apply": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": false,
          "description": "Whether to allow apply when there are no changes",
          "title": "Allow-Empty-Apply"
        },
        "auto-apply": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Whether to auto-apply the run when planned (defaults to workspace setting)",
          "title": "Auto-Apply"
        },
        "debugging-mode": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": false,
          "description": "Enable debug logging for this run",
          "title": "Debugging-Mode"
        },
        "is-destroy": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": false,
          "description": "Whether this run should destroy all resources",
          "title": "Is-Destroy"
        },
        "message": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Message to include with the run",
          "title": "Message"
        },
        "plan-only": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": false,
          "description": "Whether this is a speculative, plan-only run",
          "title": "Plan-Only"
        },
        "refresh": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": true,
          "description": "Whether to refresh state before plan",
          "title": "Refresh"
        },
        "refresh-only": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": false,
          "description": "Whether this is a refresh-only run",
          "title": "Refresh-Only"
        },
        "replace-addrs": {
          "anyOf": [
            {
              "items": {
                "type": "string"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Resource addresses to replace",
          "title": "Replace-Addrs"
        },
        "save-plan": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": false,
          "description": "Whether to save the plan without becoming the current run",
          "title": "Save-Plan"
        },
        "target-addrs": {
          "anyOf": [
            {
              "items": {
                "type": "string"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Resource addresses to target",
          "title": "Target-Addrs"
        },
        "terraform-version": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Specific Terraform version (only valid for plan-only runs)",
          "title": "Terraform-Version"
        },
        "variables": {
          "anyOf": [
            {
              "items": {
                "$ref": "#/$defs/RunVariable"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Run-specific variables",
          "title": "Variables"
        }
      },
      "title": "RunParams",
      "type": "object"
    },
    "RunVariable": {
      "description": "Model for run-specific variables.\n\nRun variables are used to provide input values for a specific run,\nwhich override any workspace variables for that run only.\n\nReference: https://developer.hashicorp.com/terraform/cloud-docs/api-docs/run#create-a-run\n\nSee:\n    docs/models/run.md for reference",
      "properties": {
        "key": {
          "description": "Variable key",
          "maxLength": 128,
          "minLength": 1,
          "title": "Key",
          "type": "string"
        },
        "value": {
          "description": "Variable value",
          "maxLength": 256,
          "title": "Value",
          "type": "string"
        }
      },
      "required": [
        "key",
        "value"
      ],
      "title": "RunVariable",
      "type": "object"
    }
  },
  "properties": {
    "params": {
      "anyOf": [
        {
          "$ref": "#/$defs/RunParams"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Params"
    },
    "workspace_id": {
      "title": "Workspace Id",
      "type": "string"
    }
  },
  "required": [
    "workspace_id"
  ],
  "type": "object"
}

terraform-cloud-mcp

Instructions

Input Schema

Input Schema (JSON Schema)

Other Tools from terraform-cloud-mcp

Related Tools

MCP directory API