In ZenHub, Workspaces are how you bundle GitHub repositories into a single view. With Workspaces, teams can give bundles of GitHub repositories names and descriptions for better project and workflow tracking. Using Workspaces, teams can also create multi-repo workflows to track otherwise silo'd repositories in the same view.
Creating a Workspace
To create a Workspace, you can get started either a single GitHub repo, or, use the multi-repo Workspace builder to merge a bundle of repositories together.
Naming single repo Workspaces
If your team works within a single GitHub repository, you can give it a Workspace name and description by opening up the Workspace navigator, and clicking Edit next to the repository name.
This will open the Workspace editor. Workspace names are independent of GitHub repository names. This means you can either name it the same as a GitHub repo, or use a more descriptive, team-focused name.
Descriptions are optional but highly recommended. Descriptions help provide clarity for the team on the purpose of the Workspace. This especially helpful if you have similar repos, but slightly different use cases per-repo.
Creating multi-repo Workspaces
To merge multiple repositories together, get started using the Repos dropdown on the top left of any ZenHub Board.
To merge repositories together, you need to have write permissions to all repositories in GitHub you'd like to merge.
Using the Add a repo + option, search for the repository that you'd like to connect. Using the avatar on the bottom left of the modal, you can toggle across all Organizations and personal repositories that you have access to. If the repository you'd like to add is in another one of your GitHub organizations, you can connect this using the custom link on the bottom left, where the avatar for your organization is located.
After confirming the repository you'd like to connect, define the ideal workflow for all connect repositories. You'll be presented with a preview screen where you can drag and drop pipelines to determine how they will be merged. When merging repositories together, the pipelines across all repositories become one, within a new Workspace.
Here's an example: In one of your repositories you have QA and in the second repository, you call the same stage in your workflow as Review. Though their names are different, they serve the same purpose, so you'll want to merge them together into one pipeline. When these pipelines are merged, the QA pipeline's Issues will appear in the Review pipeline.
When you have finished organizing your pipeline stages, click Merge to finish.
Important! Before merging Boards together, have a discussion with your team.
Post merge, the pipelines become the same across both repositories, creating a single unified Workspace after merging. While you can disconnect a repository from the central multi-repo Workspace at any time, the prioritization of all Issues inside the Board will be lost once disconnected. Make sure your team is onboard with the merge beforehand.
Once a multi-repo Workspace has been created, you can give it a name. Any un-named multi-repo Workspace will have an Untitled tag next to it.
Giving a collection of merged repos a name helps it become searchable, recognizable, and personalized to your team. Once named, the Workspace can also become a favorite in your sidebar navigation.
More about naming Workspaces
Workspace names have to be unique within ZenHub. No two ZenHub Workspaces can be named the same. Names are searched independent of case—If you name one Workspace Design and attempt to name a second design, you'll be prompted to create a unique name.
Use emojis to personalize the Workspace badge on the sidebar
Add emojis to the beginning of the Workspace name to add a personal touch to your Board experience! The emoji will as the Board badge. Adding emojis on a Mac can quickly be done using the keyboard command: control + command + space, which opens up a window directly in the text input. You can also copy-and-paste in emojis.
Setting a default repository for new Issues when using multi-repo Workspaces
When a multi-repo Workspace is created, teams can customize the default repository for where Issues go during creation.
For existing ZenHub users, previously the New Issue button defaulted to the repository that you navigated from. If you entered a multi-repo Board from repository A, the New Issue button would create the Issue in repository A unless you otherwise switched it using the + dropdown.
Regardless of which repository you navigate from in GitHub, this new default setting will streamline Issue creation. The default will automatically be set to the first repository in the list of a multi-repo Workspace. To change the default, get started by creating a New Issue.
Use the Create in X repository dropdown to select a different default repository.
Changing the default is a global change, this means if you change the default, all other team members will now also have their Issues created in the newly set default repository.
You can also re-enter the Edit screen via the Workspace navigator to set the default in Edit mode. Hovering over any connected repository gives the option to make it the Default and Disconnect.
Reminder—Disconnecting repos is a global change that impacts everyone's workflow. Read more on permissions and changes to the Board that impact everyone.
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.
Once favorited, it'll be added to the sidebar navigation for easy access.
In addition to searching the repository names, the sidebar navigation also searches Workspaces names for related Workspaces that match your search.
The next phase of Workspaces
Naming Workspaces is just the beginning! We have multiple phases upcoming for Workspaces, and share a detailed overview of the upcoming phases in our roadmap here.