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.

Notes on Workspaces

Things to know before creating Workspaces

• When creating Workspaces, you can select up to 5 repos at a time, but you can go through selecting up to 5 repos as many times as you need to map all your repos to a Workspace in a single workflow. 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 repo combos and load times.
• Names of Workspaces need to be unique.
• Default repo settings in a Workspace are unique to you — the repo you identify as the default is where when creating new Issues, the new Issue modal will default to in the repo dropdown. (More on this below)

Creating Workspaces

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.

When navigating in Zenhub, you can create a Workspace at any time through the Create new Workspace button on the Workspace navigator:

When creating Workspaces, you need to add repositories that will be apart of this Workspace. 

Once you've selected the repositories you want in the Workspace, be sure to set a default. This default is where new Issues will be created and is a custom setting that every individual can set. The default setting applies only to you, for when you create new Issues

Optimizing load times

During creation, a load indicator will notify teams of the impact on load times merging might have. Learn more

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,  click Create new Workspace to enter the pipeline merge modal. Next, define the ideal workflow for all connect repositories in your new Workspace. 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.

When looking at each merge "card" you'll see the name of the repo, and the pipeline name (in bold), and the count of Issues that currently exist in that pipeline. We'll predict and map similar pipeline names to be merged, but hover over the card and use the arrows to modify where that pipeline should land in the new Workspace if it doesn't align when your new workflow. 

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.

If you do not need a pipeline, or need to create a new one, click into the setting gear to rename and delete, or scroll to the right to create a new one. 

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.

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.

Searching Workspaces

In addition to searching the repository names, the sidebar navigation also searches Workspaces names for related Workspaces that match your search.