Add workspace run task feature

[KshitijaChoudhari]

feat(workspace-run-tasks): add workspace run tasks support

Description

This PR adds comprehensive support for Terraform Cloud/Enterprise Workspace Run Tasks to the python-tfe SDK. This feature allows developers to manage run tasks at the workspace level, enabling custom policy enforcement, validation, and automation workflows specific to individual workspaces.

It provides full CRUD operations for creating, reading, updating, and deleting workspace run tasks, with support for different enforcement levels and execution stages.

Testing plan

• Unit Tests: 28 workspace run tasks tests covering all models, CRUD operations, and functionality
• Integration Testing: Validated end-to-end flow with real HCP Terraform Cloud
• All Tests: 365/365 unit tests passing, full test suite validates implementation

External links

• API documentation (Workspace Run Tasks API):
  https://developer.hashicorp.com/terraform/cloud-docs/api-docs/workspaces#run-tasks
• Run Tasks overview / Terraform Cloud documentation:
  https://developer.hashicorp.com/terraform/cloud-docs/workspaces/settings/run-tasks

Output from tests

Including output from tests may require access to a TFE instance. Ignore this section if you have no environment to test against.

Unit Tests (All Passing):

$ pytest tests/units/test_workspace_run_tasks.py -v
platform darwin -- Python 3.14.0, pytest-9.0.1, pluggy-1.6.0
collected 365 items

tests/units/test_workspace_run_tasks.py::TestWorkspaceRunTask::test_create_minimal PASSED
tests/units/test_workspace_run_tasks.py::TestWorkspaceRunTask::test_create_complete PASSED
tests/units/test_workspace_run_tasks.py::TestWorkspaceRunTask::test_read PASSED
tests/units/test_workspace_run_tasks.py::TestWorkspaceRunTask::test_update PASSED
tests/units/test_workspace_run_tasks.py::TestWorkspaceRunTask::test_delete PASSED
tests/units/test_workspace_run_tasks.py::TestWorkspaceRunTask::test_list PASSED
tests/units/test_workspace_run_tasks.py::TestWorkspaceRunTask::test_list_with_filters PASSED
tests/units/test_workspace_run_tasks.py::TestWorkspaceRunTask::test_enforcement_levels PASSED
tests/units/test_workspace_run_tasks.py::TestWorkspaceRunTask::test_execution_stages PASSED
tests/units/test_workspace_run_tasks.py::TestWorkspaceRunTask::test_relationships PASSED
... (additional tests passed)

Linting and Type Checks (All Passing):

$ make check
.venv/bin/python -m ruff format --check .
136 files already formatted
.venv/bin/python -m ruff check .
All checks passed!
.venv/bin/python -m mypy src/pytfe
Success: no issues found in 84 source files

Real HCP Terraform Cloud Integration (PASSED):

• Workspace run tasks created and configured successfully
• CRUD operations validated against live TFC workspace
• Enforcement levels and stages properly applied
• Complete workspace-level run task management verified

Test Coverage Summary:

• Unit Tests: 28/28 workspace run tasks tests passing (100%)
• Integration Tests: Real HCP Terraform Cloud validation successful
• Code Quality: All linting, formatting, and type checks passing

Rollback Plan

Low Risk Assessment: This is an additive feature that introduces new functionality without modifying existing SDK behavior. No breaking changes to current users.

Rollback Strategy:

Immediate rollback (if critical issues discovered):

• Revert commits from feat/workspace-run-task branch
• Remove files:
  • examples/workspace_run_tasks.py
  • src/pytfe/models/workspace_run_task.py
  • src/pytfe/resources/workspace_run_tasks.py
  • tests/units/test_workspace_run_tasks.py
• Remove exports from __init__.py
• Timeline: Within 2 hours of issue detection

Partial rollback (if example issues only):

• Remove example file only: examples/workspace_run_tasks.py
• Keep core SDK functionality intact
• Update documentation to indicate feature is available but example is being revised
• Timeline: Within 24 hours

Monitoring Plan

• Monitor SDK installation/import success rates
• Check for new GitHub issues related to workspace run tasks
• Verify existing functionality remains unaffected
• Review package build and distribution processes

Communication Plan

• Update GitHub issue/PR with rollback notice
• Post notice in project documentation if needed
• Notify users via release notes of any temporary removal

Breaking Changes

No breaking changes. All new functionality is additive and does not modify existing SDK behavior.

Changes to Security Controls

No changes to existing security controls. This feature leverages existing SDK security patterns without modification.

Security Implementation Details:

• Token Handling: Uses existing client authentication patterns; no new token handling mechanisms
• Input Validation: Validated via Pydantic models with strict typing; invalid inputs rejected with proper error handling
• Transport Security: Uses existing HTTPS transport; no TLS/SSL changes
• Access Controls: No authn/authz changes; uses existing permission model
• Logging Security: No sensitive data logged in plain text; follows existing logging patterns

Risk Assessment: Low security risk.

PCI review checklist

• I have documented a clear reason for, and description of, the change I am making.
• If applicable, I've documented a plan to revert these changes if they require more than reverting the pull request.
• If applicable, I've documented the impact of any changes to security controls.