Workflows

Automate issue movement between workspaces for team handoffs and cross-functional coordination

When You Need Workflows

Workflows solve coordination problems between teams working in separate workspaces. When your development team finishes work that needs QA review, when design hands off completed mockups to engineering, or when management needs portfolio visibility across multiple team workspaces, Workflows automate the handoff so issues move automatically without manual updates or status reporting meetings.

You don't need Workflows if your entire team works in a single workspace. Within-workspace automation is handled by Smart Pipelines, which manage metadata and WIP limits for a single team's board.

Workflows specifically address cross-workspace scenarios where issues need to move between different teams' boards based on pipeline status. This creates seamless handoffs, ensures stakeholder visibility, and eliminates the duplicate work of manually updating multiple boards when work changes hands.

Understanding Workflow Components

Workflows connect pipelines across different workspaces, creating automatic issue movement rules. When an issue reaches a specific pipeline in one workspace (the trigger), it automatically moves to a designated pipeline in another workspace (the destination).

• Trigger pipeline: The pipeline that initiates automatic movement when issues enter it. In the Workflows Builder interface, trigger pipelines appear as circles.

• Destination pipeline: Where issues automatically move after being triggered. Destination pipelines appear as triangles in the interface.

• Source workspace: The workspace containing the trigger pipeline, typically where work begins or gets completed.

• Target workspace: The workspace containing the destination pipeline, where work moves for the next team or stakeholder.

The Workflows Builder displays your current workspace at the top with connected workspaces below. Lines between pipelines show active automation rules, making it easy to visualize how issues flow between teams.

Creating Your First Workflow

Navigate to the workspace where you want to configure automation and click ⚙ Edit Workspace in the left sidebar, then select Edit Workflows. This opens the Workflows Builder showing all workflows related to your current workspace.

Creating a workflow connection requires four decisions:

1. Select trigger pipeline - Choose which pipeline in your current workspace will initiate automatic movement

2. Choose target workspace - Select which workspace should receive the issues

3. Select destination pipeline - Pick which pipeline in the target workspace should receive issues

4. Configure scope - Decide whether to move current issues, future issues, or both

Test your workflow with a non-critical issue before enabling it for your entire team. Move an issue into the trigger pipeline and verify it appears in the correct destination pipeline within the target workspace. This validation prevents surprises when your workflow activates for real work.

Viewing and Managing Workflows

Click ⚙ Edit Workspace in the left sidebar, then select Edit Workflows to see all workflows for your current workspace. The Workflows Builder shows which workspaces connect to your current workspace and which pipelines trigger automatic movement.

Each workflow appears as a line connecting pipelines between workspaces. You can modify connections by clicking on existing workflows to change trigger or destination pipelines, remove workflows that no longer serve your process, or add new automation rules as teams identify additional handoff points.

Monitor workflow effectiveness through reduced manual board updates, improved cross-team communication patterns, and issue movement patterns that match your intended handoff process.

Common Workflow Patterns

Development to QA handoff

Moving issues to "Ready for QA" in Development workspace → Automatically appears in "Backlog" in QA workspace. QA team immediately knows work is ready for testing without manual notification.

Design to development handoff

Moving work to "Design Complete" in Design workspace → Automatically appears in "Ready for Development" in Engineering workspace. Seamless coordination without designers manually notifying developers.

Support to engineering escalation

Moving support tickets to "Escalated" in Support workspace → Automatically creates corresponding work in Engineering backlog. Maintains connection between customer reports and technical fixes.

Management rollup for portfolio visibility

Create a dedicated management workspace with simplified pipelines: Backlog, In Progress, In Review, Closed.

Configure multiple team "Done" pipelines → Management "Completed" pipeline. Team "Blocked" pipelines → Management "At Risk" pipeline. Active development pipelines → Management "Active Work" pipeline.

This ensures management sees current progress across all teams without requiring individual teams to maintain separate stakeholder reporting boards.

Workflow Rules and Limitations

Workflows only work with GitHub issues. Zenhub issues cannot be moved between workspaces using workflow automation. If you need to coordinate Zenhub-specific work across teams, you'll need to manually update boards or convert Zenhub issues to GitHub issues first.

You cannot create circular loops using the same pipelines. While you can have multiple workflows moving issues in both directions between workspaces, you cannot sync the same two pipelines bidirectionally.

For example, if Workspace A "Ready for QA" triggers movement to Workspace B "Backlog," you cannot also have Workspace B "Backlog" trigger movement back to Workspace A "Ready for QA." This prevents endless loops where issues bounce back and forth between the same pipeline pair.

The Closed pipeline cannot be used as a trigger or destination. Once issues close, they've completed the workflow cycle and shouldn't trigger additional automated movement. Design your workflows to hand off work before the final closure step.

One trigger pipeline can send issues to multiple destination workspaces. However, you cannot send one trigger to multiple pipelines within the same destination workspace. Each trigger creates one specific destination connection per workspace.

Users need write permissions to at least one repository in both the source and target workspaces to create or modify workflows. Without appropriate permissions, workflow creation will fail even if the interface allows you to attempt configuration.

Workflow Direction and Best Practices

Workflows are unidirectional - they move issues from a source workspace to a destination workspace. The system prevents circular dependencies by design, so you can't accidentally create loops where issues bounce back and forth endlessly between workspaces.

Design your workflows with clear directionality by establishing source workspaces where work originates or gets completed, and destination workspaces that receive work for the next phase. For example, your Development workspace acts as the source that feeds completed work to your QA workspace (the destination).

For management rollup patterns, team workspaces serve as sources feeding into a central management workspace (the destination). This creates a hub-and-spoke pattern where multiple team workspaces all route status updates to a single portfolio view without creating conflicting automation.

When several workflows affect related pipelines, ensure they move issues in consistent directions. For example, if Development → QA and QA → Staging, your pipeline triggers should create a clear progression through your development process.

Troubleshooting Workflows

Permission issues: Verify that users have appropriate GitHub repository access in both workspaces. Workflow automation respects GitHub permissions, so users without proper access won't see automatic issue movement even when workflows are correctly configured.

Zenhub issue limitations: If issues aren't moving through workflows, verify they're GitHub issues rather than Zenhub issues. Only GitHub issues support workflow automation between workspaces.

Issues not appearing in destination workspace: Confirm that pipeline names haven't been deleted and recreated. While renaming pipelines is safe, deleting and recreating them breaks workflow connections and requires you to update the affected workflows.

FAQ

Q: Can I create workflows between workspaces I don't manage?
A: You need write permissions to at least one repository in each workspace to create workflows between them. Coordinate with workspace administrators if you lack necessary permissions.

Q: What happens if I rename a pipeline that's part of a workflow?
A: Renaming pipelines will not break workflows that reference those pipeline names. However if pipelines are deleted and recreated you'll need to update or recreate the affected workflows.

Q: Should my source workspace or destination workspace "own" the work?
A: The source workspace is where work gets completed before handoff, while the destination workspace handles the next phase. For Dev→QA workflows, Development is the source and QA is the destination. For management rollups, team workspaces are sources feeding a management destination.

Q: How do I temporarily disable a workflow without deleting it?
A: Currently, workflows are either active or deleted. To temporarily disable automation, you'll need to remove the workflow connection and recreate it when needed.

Q: Why don't my Zenhub issues move through workflows?
A: Workflows only work with GitHub issues. Zenhub issues cannot be moved between workspaces using workflow automation.

Q: Can I see a history of which workflows moved an issue?
A: Yes, workflow movements appear in the issue's activity history showing which pipeline the issue moved from and to, which workspace it moved to, and when the workflow triggered. You'll also see real-time notifications on your board when moving issues that trigger workflows.