What is a Workspace?
A Workspace is how you keep Issues in GitHub organized using ZenHub. You can add any number of GitHub repos into the same ZenHub Workspace, letting your team benefit from a shared view on all your work. With ZenHub Workspaces, the same GitHub repository can be added to multiple Boards. In other words, Issues and Epics can be added and updated in different Workspaces at the same time yet have an independent pipeline allocation for each Workspace. This empowers teams who share repos, but have otherwise independent workflows, to no longer have to share the same pipeline flow across the Board.
With Workspaces you can:
- Create multiple Workspaces from the same repos. This means teams can work on the same set of Issues without compromising on the order and set of pipelines.
- View an Issue to see the progress and status in every single Workspace. Easily update the Issue’s pipeline in your Workspace without compromising other teams’ workflows. Any updates to the Issues or Epics (content, labels, Estimates, etc) are reflected in all related Workspaces.
- Navigate through your teams’ Workspaces to instantly see the status of all the Issues and Epics. Easily check the progress of each area to gain full visibility. Learn more about navigating your Workspace.
- Automate the movement of Issues between team Workspaces. That means teams can manage the progress of multiple teams in a single view, automate the hand-off of work between teams and reduce manual Board updates.
Teams using ZenHub Enterprise must be on ZenHub Enterprise 2.36 or above in order to create multiple Workspaces with the same repository
Setting up Workspaces
- Click the Create new Workspace button on the Workspace navigator or select “Edit Workspace” to update an existing Workspace. If you create a new repo, you will automatically be prompted to create a Workspace when you view it in ZenHub.
- Give your Workspace a name and description. Names of Workspaces must be unique and therefore no two Workspaces can be named the same.
- Add any number of repositories you would like to be part of this Workspace. You can add multiple repositories to the Workspace by selecting the +Add Reposoption.
- Up to five repos can be added at a time. However, you can repeat this process as many times as required. As you add repos, you'll get a performance load time indicator to help determine how the amount of repos you're connecting will potentially impact load times. Learn more about how to optimize Workspaces for performance (including loading a subset of issues via labels).
- Add repos from another organization by using the avatar on the bottom left of the modal.
- Once you've selected the repositories you want in your Workspace, be sure to set a default. From now on, new Issues will be created in this repo unless another repo has been selected during creation. The default setting applies only when creating new Issues and is a user setting, not a team setting. This can be updated when creating or editing a Workspace.
IMPORTANT: When you add a repo, all of the Issues in will appear in the new Workspace.
- Once you are happy with the repositories you'd like to connect, click Finish. This will bring you to your newly created Workspace. Issues are automatically sorted into relevant Pipelines, reducing the amount of setup time required. Issues will be sorted according to these triggers:
- Issues in the current Milestone will be moved to Sprint Backlog
- Issues with no recent activity will be moved to Icebox
- Issues with connected PRs will be moved to in progress
- Note: for customers using ZenHub On-Premise, please follow our guide on Issue Placement for your Workspace here
Leverage Workflows to copy Issue placement from another Workspace.
If you'd like to copy the pipeline placement from an existing Workspace we'd recommend leveraging ZenHub Workflows. Select the Workflows tab where you'll see your current Workspace listed at the top of the page. All related Workspaces (Workspaces which contain at least one of the repos in your current Workspace) are listed below:
Set up Workflow connections so that current and future Issues from an existing Workspace automatically move to your desired pipelines in your current Workspace. Example: As seen below, we're setting up Workflow connections so that current and future Issues in pipelines from the Demo Board! Workspace will automatically move to the destination pipelines in the current Team Success Workspace :
Favorite a Workspace
If you frequent the same few Workspaces to manage your work, once a Workspace is named you can favorite it to have it at the top of the Workspace navigator. Click the star next to the Workspace name on the sidebar to add it to your favorites: