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.

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 is the pipeline that initiates automatic movement when issues enter it. In the Workflows Builder interface, trigger pipelines appear as circles.

Destination pipeline is where issues automatically move after being triggered. Destination pipelines appear as triangles in the interface.

Source workspace is the workspace containing the trigger pipeline, typically where work begins or gets completed.

Target workspace is 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 4 decisions:

1. Select a trigger pipeline in your current workspace

2. Choose the target workspace that should receive the issues

3. Select the destination pipeline in that workspace

4. Configure scope — 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.

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.

Common workflow patterns

Development to QA handoff
Moving issues to Ready for QA in the Development workspace automatically places them in Backlog in the QA workspace. The QA team immediately knows work is ready for testing without manual notification.

Design to development handoff
Moving work to Design Complete in the Design workspace automatically places it in Ready for Development in the Engineering workspace. Seamless coordination without designers manually notifying developers.

Support to engineering escalation
Moving support tickets to Escalated in the Support workspace automatically creates corresponding work in the Engineering backlog. Maintains the 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, and Closed. Configure team Done pipelines to route to a management Completed pipeline, Blocked pipelines to an At Risk pipeline, and active development pipelines to an Active Work pipeline. Management sees current progress across all teams without requiring separate reporting.

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, convert Zenhub issues to GitHub issues first.

Circular loops using the same pipelines are not supported. If Workspace A's Ready for QA triggers movement to Workspace B's Backlog, you cannot also have Workspace B's Backlog trigger movement back to Workspace A's Ready for QA. This prevents issues from bouncing endlessly 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. 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.

Users need write permissions to at least one repository in both the source and target workspaces to create or modify workflows.

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.

Issues not moving
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 the necessary permissions.

Q: What happens if I rename a pipeline that's part of a workflow?
A: Renaming pipelines won't break existing workflows. However, if you delete and recreate a pipeline, you'll need to update or recreate the affected workflows.

Q: How do I temporarily disable a workflow without deleting it?
A: Workflows are either active or deleted. To temporarily disable automation, 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.