Workspace Task Orchestration¶

Run tasks across multiple repositories in your workspace with streaming output and comprehensive error handling.

🤖 AI-Generated Content

This documentation was generated with AI assistance and is still being audited. Some, or potentially a lot, of this information may be inaccurate. Learn more.

Overview¶

The workspace task orchestration feature allows you to execute tasks defined in wrknv.toml across all repositories in your workspace with a single command. This is particularly useful for:

Running tests across your entire ecosystem
Performing code quality checks on multiple packages
Building all packages in a monorepo-style workflow
Running any task consistently across related projects

Quick Start¶

# Run tests across all repositories in workspace
we workspace run test

# Run typecheck on specific packages
we workspace run typecheck --repos="pyvider-*"

# Parallel execution
we workspace run test --parallel

# Stop on first failure
we workspace run test --fail-fast

Command Syntax¶

we workspace run <task> [OPTIONS]

Arguments¶

task (required): Name of the task to run (e.g., test, typecheck, build)
Must exist in each repository's wrknv.toml
Repositories without the task are skipped automatically

Options¶

--repos=PATTERN: Glob pattern to filter repositories
Default: All repositories in workspace
Examples: "pyvider-*", "terraform-provider-*", "wrknv"
Supports standard glob patterns (*, ?, [])
--parallel: Run tasks in parallel across repositories
Default: Sequential execution
Sequential provides clearer output ordering
Parallel is faster for independent tasks
--fail-fast: Stop on first failure (sequential mode only)
Default: Continue on error (collect all results)
Useful for CI/CD pipelines
Ignored in parallel mode

Execution Modes¶

Sequential Execution (Default)¶

Runs tasks one repository at a time, with clear output separation:

we workspace run test

Benefits: - Clear, ordered output per repository - Easy to debug failures - Fail-fast support - Real-time streaming output

Output Format:

================================================================================
▶ Running 'test' in pyvider
================================================================================
[test output from pyvider]

✓ Task 'test' succeeded in pyvider (2.1s)

================================================================================
▶ Running 'test' in pyvider-cty
================================================================================
[test output from pyvider-cty]

✓ Task 'test' succeeded in pyvider-cty (1.8s)

================================================================================
📊 Workspace Task Summary
================================================================================
Task: test
Total repos: 2
✅ Succeeded: 2
❌ Failed: 0
⏭️  Skipped: 0
⏱️  Duration: 4.2s

✅ All repositories succeeded!

Parallel Execution¶

Runs tasks concurrently across all repositories:

we workspace run test --parallel

Benefits: - Faster execution - Efficient use of system resources - Good for independent tasks

Considerations: - Output may be interleaved - No fail-fast support (all repos run to completion) - Harder to debug failures in real-time

Repository Discovery¶

Auto-Discovery¶

By default, the workspace orchestrator discovers all Git repositories with pyproject.toml files in the parent directory of your current location:

# From /path/to/workspace/wrknv
we workspace run test
# Discovers all repos in /path/to/workspace/

Pattern-Based Filtering¶

Filter repositories using glob patterns:

# Only pyvider-* packages
we workspace run test --repos="pyvider-*"

# Specific repository
we workspace run typecheck --repos="wrknv"

# Multiple patterns (use shell expansion)
we workspace run lint --repos="pyvider-{cty,hcl,rpcplugin}"

# Terraform providers only
we workspace run build --repos="terraform-provider-*"

Task Requirements¶

For a task to run in a repository:

Repository must have:
.git directory (Git repository)
pyproject.toml file (Python project)

Task must be defined in wrknv.toml:

[tasks]
test = "pytest"
typecheck = "mypy src/"

If task is missing:
Repository is automatically skipped
Counted in "Skipped" metric
Warning logged but not treated as failure

Environment Isolation¶

Each repository executes in its own isolated environment:

Independent virtual environments: Each repo uses its own workenv/ or .venv/
Auto-detection: Environment execution mode detected per-repo
Editable installs: Automatically detected and handled correctly
PATH management: Virtual environment bins properly prepended
No cross-contamination: Dependencies isolated between projects

Error Handling¶

Continue-on-Error (Default)¶

By default, all repositories are tested even if some fail:

we workspace run test

Summary includes: - Total repositories processed - Succeeded count - Failed count with repo names and exit codes - Skipped count - Total duration

Exit Code: - 0 if all repositories succeeded - 1 if any repository failed

Fail-Fast Mode¶

Stop on first failure (sequential mode only):

we workspace run test --fail-fast

Behavior: - Stops immediately when any task fails - Remaining repositories are not processed - Faster feedback in CI/CD - Only works in sequential mode (ignored with --parallel)

Real-World Examples¶

Development Workflow¶

# Format all code
we workspace run format

# Check formatting without changes
we workspace run format.check

# Lint all projects
we workspace run lint

# Type check everything
we workspace run typecheck

# Run all quality checks
we workspace run quality

Testing Workflow¶

# Run unit tests everywhere
we workspace run test.unit

# Run all tests with coverage
we workspace run test.coverage

# Parallel test execution for speed
we workspace run test --parallel

# Test specific package family
we workspace run test --repos="pyvider-*"

CI/CD Pipeline¶

# Quality gate (fail-fast for quick feedback)
we workspace run quality --fail-fast

# Comprehensive test suite
we workspace run test.coverage

# Build all packages
we workspace run build --parallel

# Verify installations
we workspace run pkg.install --fail-fast

Package-Specific Operations¶

# Update all pyvider plugins
we workspace run pkg.lock --repos="pyvider-*"

# Build terraform providers
we workspace run build --repos="terraform-provider-*"

# Run integration tests on core packages
we workspace run test.integration --repos="{wrknv,pyvider,flavorpack}"

Performance Considerations¶

When to Use Sequential¶

Debugging failures
Clear output required
Tasks modify shared resources
Fail-fast behavior needed

When to Use Parallel¶

Independent tasks
Many repositories
CI/CD pipelines (when fail-fast not needed)
Tasks are I/O bound or slow

Optimization Tips¶

Use specific filters: Don't run tasks on repos that don't need them

# Bad: runs on all repos, many skipped
we workspace run test

# Good: only relevant repos
we workspace run test --repos="pyvider-*"

Combine with parallel for speed:

we workspace run typecheck --repos="pyvider-*" --parallel

Use fail-fast in CI for quick feedback:
```
we workspace run quality --fail-fast
```

Integration with Existing Features¶

Task Auto-Detection¶

Environment auto-detection works per-repository: - Each repo's environment is detected independently - uv run prefix added automatically when needed - Editable installs detected and handled correctly

Process Streaming¶

All task output is streamed in real-time: - See progress as it happens - Process titles show current repo - Same streaming behavior as we run <task>

Task Execution Environment¶

Respects all task configuration: - timeout: Per-task timeouts - stream_output: Streaming preferences - execution_mode: Environment detection mode - env: Task-specific environment variables

Troubleshooting¶

No Repositories Found¶

⚠️ No repositories found

Solutions: - Ensure you're in a workspace directory - Check that sibling directories have .git and pyproject.toml - Verify --repos pattern is correct - Use we workspace status to see discovered repos

Task Not Found in Repository¶

⚠️ Task 'test' not found in pyvider-cty

Solutions: - Add task to repository's wrknv.toml - Use different filter to exclude repos without task - Task will be skipped automatically (not an error)

All Tasks Failing¶

❌ Task 'test' failed in wrknv (exit code: 1)
❌ Task 'test' failed in pyvider (exit code: 1)

Solutions: - Check task works in individual repos: we run test - Verify environment is set up: we setup - Check for dependency issues: uv sync - Review stderr output for specific errors

Parallel Execution Issues¶

If parallel execution causes problems: - Use sequential mode instead - Tasks may have shared resource conflicts - Output may be too interleaved to debug