feat(run-tasks): add run tasks integration support #78
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
- Add RunTasksIntegration resource with callback method - Add RunTaskRequest model for webhook payload parsing - Add TaskResultCallbackOptions, TaskResultOutcome, TaskResultStatus models - Add example Flask server for run tasks webhooks - Add 15 unit tests for run tasks integration - Update client to include run_tasks_integration property - Export RunTaskRequest model
Flask dependency removed completely from the project
- Add task_result.py with TaskResult, TaskResultStatus, TaskEnforcementLevel models - Add task_stages.py with TaskStage, Stage, TaskStageStatus, Actions, Permissions models - Update run_task.py to import Stage and TaskEnforcementLevel from new modules (remove duplicates) - Update run_tasks_integration.py to use TaskResultStatus enum from task_result - Update run_task_request.py to add model_config for proper serialization - Export all new models in __init__.py - All 22 unit tests passing - Matches go-tfe implementation structure
- Add all new run tasks integration models to __all__ exports - Fix trailing whitespace issues across multiple files - Run ruff format to ensure consistent code style - All 22 unit tests passing - All linting checks pass
This commit adds comprehensive support for Terraform Cloud/Enterprise Run Tasks Integration to the python-tfe SDK. This feature allows developers to create webhook servers that can validate Terraform runs and send results back to TFC/TFE. Key additions: - Production-ready webhook server example with deployment instructions - Complete documentation explaining architecture and flow - Support for multiple cloud deployment platforms (AWS EC2, Heroku, GCP, etc.) - Comprehensive validation examples (cost control, security, compliance) - Clean implementation following HashiCorp patterns
KshitijaChoudhari
changed the title
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
feat(run-tasks): add run tasks integration support
Description
This PR adds comprehensive support for Terraform Cloud/Enterprise Run Tasks Integration to the python-tfe SDK. This feature allows developers to create webhook servers that can validate Terraform runs and send results back to TFC/TFE, enabling custom policy enforcement, cost validation, security scanning, and approval workflows.
Testing plan
External links
** [API documentation]**
Run Tasks Integration API
Run Tasks Overview
Run Tasks API Reference
[Related PR]
[HashiCorp go-tfe SDK Run Tasks]
(vscode-file://vscode-app/Applications/Visual%20Studio%20Code.app/Contents/Resources/app/out/vs/code/electron-browser/workbench/workbench.html)
[Terraform Cloud Run Tasks Documentation]
(vscode-file://vscode-app/Applications/Visual%20Studio%20Code.app/Contents/Resources/app/out/vs/code/electron-browser/workbench/workbench.html)
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/ -v
platform darwin -- Python 3.14.0, pytest-9.0.1, pluggy-1.6.0
collected 339 items
tests/units/test_run_tasks_integration.py::TestRunTaskRequest::test_run_task_request_minimal PASSED
tests/units/test_run_tasks_integration.py::TestRunTaskRequest::test_run_task_request_complete PASSED
tests/units/test_run_tasks_integration.py::TestTaskResultTag::test_tag_with_level PASSED
tests/units/test_run_tasks_integration.py::TestTaskResultTag::test_tag_without_level PASSED
tests/units/test_run_tasks_integration.py::TestTaskResultOutcome::test_outcome_complete PASSED
tests/units/test_run_tasks_integration.py::TestTaskResultOutcome::test_outcome_minimal PASSED
tests/units/test_run_tasks_integration.py::TestTaskResultCallbackOptions::test_callback_options_passed PASSED
tests/units/test_run_tasks_integration.py::TestTaskResultCallbackOptions::test_callback_options_with_outcomes PASSED
tests/units/test_run_tasks_integration.py::TestTaskResultCallbackOptions::test_validate_invalid_status PASSED
tests/units/test_run_tasks_integration.py::TestTaskResultCallbackOptions::test_validate_valid_statuses PASSED
tests/units/test_run_tasks_integration.py::TestRunTasksIntegration::test_callback_success PASSED
tests/units/test_run_tasks_integration.py::TestRunTasksIntegration::test_callback_empty_url PASSED
tests/units/test_run_tasks_integration.py::TestRunTasksIntegration::test_callback_empty_token PASSED
tests/units/test_run_tasks_integration.py::TestRunTasksIntegration::test_callback_invalid_status PASSED
tests/units/test_run_tasks_integration.py::TestRunTasksIntegration::test_callback_with_outcomes PASSED
Linting and Type Checks (All Passing):
$ make check
.venv/bin/python -m ruff format --check .
134 files already formatted
.venv/bin/python -m ruff check .
All checks passed!
.venv/bin/python -m mypy src/pytfe
Success: no issues found in 82 source files
Production Testing on AWS EC2 (PASSED):
Deployed to AWS EC2: :8888
$ python examples/run_tasks_integration.py --port 8888
Run Tasks Integration Callback Server
Listening on http://localhost:8888
Waiting for requests from TFC/TFE...
Received Run Task Request
Run ID: run-abc123def
Organization: my-test-org
Workspace: test-workspace
Stage: pre_plan
Callback URL: https://app.terraform.io/api/v2/task-results/...
[OK] Verification request detected - responding with 200 OK
Initializing TFEClient...
Access token from webhook: AtH4Xk2Y9Z***
Client initialized successfully
Sending callback to: https://app.terraform.io/api/v2/task-results...
[SUCCESS] Callback sent successfully: passed
Including output from tests may require access to a TFE instance. Ignore this section if you have no environment to test against.
Real HCP Terraform Cloud Integration (PASSED):
Run task created and configured successfully
Webhook received from actual TFC run trigger
Callback sent and acknowledged by TFC API
Results displayed correctly in TFC UI as "Advisory - Passed"
Complete end-to-end flow verified with production TFC instance
Local Mock Testing (PASSED):
Mock TFC/TFE received callback!
Status: passed
Message: All checks passed successfully
All tests completed successfully
Test Coverage Summary:
Unit Tests: 22/22 run tasks integration tests passing (100%)
Integration Tests: Local mock server validation successful
Production Testing: AWS EC2 deployment with real webhooks successful
End-to-End: Complete TFC/TFE integration flow validated
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):
35d2296from main branchexamples/run_tasks_integration.pyanddocs/RUN_TASKS_INTEGRATION_EXAMPLE.mdsrc/pytfe/models/__init__.pyfor run tasks modelsPartial Rollback (if example issues only):
examples/run_tasks_integration.pyMonitoring Plan:
Communication Plan:
Risk Mitigation: Since this feature is purely additive and doesn't modify existing code paths, rollback risk is minimal. Existing users will not be affected by reverting these changes.
Changes to Security Controls
Breaking Changes
All new functionality is additive and does not modify existing SDK behavior. Existing code continues to work unchanged.
Changes to Security Controls
No changes to existing security controls. This feature leverages existing SDK security patterns without modification.
Security Implementation Details:
Token Handling:
token[:10]***)Input Validation:
Transport Security:
Access Controls:
Logging Security:
Risk Assessment: Low security risk. Feature uses established, tested security controls from the existing SDK without introducing new attack vectors or modifying existing security mechanisms.
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.
Examples of changes to security controls include using new access control methods, adding or removing logging pipelines, etc.
If you have any questions, please contact your direct supervisor, GRC (#team-grc), or the PCI working group (#proj-pci-reboot). You can also find more information at PCI Compliance.