What is a Workspace?
A Workspace is how you keep Issues in GitHub organized using ZenHub. You can add any number of GitHub repositories into the same ZenHub Workspace, letting your team benefit from a shared view of all your work. With ZenHub Workspaces, the same GitHub repository can be added to multiple Boards. This allows individual teams to work on the same set of Issues but follow their own workflow and pipeline structure. When setting up your Workspaces in ZenHub we encourage all teams big and small to think about the hand-offs, stakeholders, and collaborators within their ecosystem and leverage Workflows to connect team Workspaces and surface the big picture. The first step is to think about your team's use case and the types of hand-offs, or transitions that typically take place.
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.
- Connect team Workspaces using automated Workflows. 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. Learn more
- 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.
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-Premises, 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: