lock_workspace
Prevent infrastructure changes by locking a Terraform Cloud workspace during maintenance or manual adjustments. This stops new runs from queuing while allowing current operations to complete.
Instructions
Lock a workspace.
Locks a workspace to prevent runs from being queued. This is useful when you want to prevent changes to infrastructure while performing maintenance or making manual adjustments. Locking a workspace does not affect currently running plans or applies.
API endpoint: POST /workspaces/{workspace_id}/actions/lock
Args: workspace_id: The ID of the workspace to lock (format: "ws-xxxxxxxx") reason: Optional reason for locking
Returns: The workspace with updated lock status and related metadata
See: docs/tools/workspace.md for reference documentation
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| workspace_id | Yes | ||
| reason | No |
Implementation Reference
- The core handler function decorated with error handling that implements the lock_workspace tool. It constructs a payload with an optional reason and performs a POST request to the Terraform Cloud API endpoint /workspaces/{workspace_id}/actions/lock to lock the workspace.
@handle_api_errors async def lock_workspace(workspace_id: str, reason: str = "") -> APIResponse: """Lock a workspace. Locks a workspace to prevent runs from being queued. This is useful when you want to prevent changes to infrastructure while performing maintenance or making manual adjustments. Locking a workspace does not affect currently running plans or applies. API endpoint: POST /workspaces/{workspace_id}/actions/lock Args: workspace_id: The ID of the workspace to lock (format: "ws-xxxxxxxx") reason: Optional reason for locking Returns: The workspace with updated lock status and related metadata See: docs/tools/workspace.md for reference documentation """ payload = {} if reason: payload = {"reason": reason} return await api_request( f"workspaces/{workspace_id}/actions/lock", method="POST", data=payload ) - terraform_cloud_mcp/server.py:59-59 (registration)Registers the lock_workspace function as an MCP tool using the FastMCP server instance with write_tool_config (enabling it unless in read-only mode).
mcp.tool(**write_tool_config)(workspaces.lock_workspace) - terraform_cloud_mcp/server.py:39-42 (helper)Configuration dictionary used in the registration of write-enabled tools like lock_workspace, controlling enablement based on read-only mode and adding annotations.
write_tool_config = { "enabled": not read_only_mode, "annotations": {"readOnlyHint": False} } - terraform_cloud_mcp/server.py:14-14 (registration)Imports the workspaces module containing the lock_workspace handler function for use in tool registration.
from terraform_cloud_mcp.tools import workspaces