Note: to have information organized on a ZenHub Board, a repository must belong to a Workspace. Learn more about setting up your Workspaces here.
There are three options when organizing repos in your Workspace:
- Remove a repo - removes a repo from the Workspace and does not add it to a new Workspace.
- Split a repo into its own Workspace - removes a repo from the Workspace and creates a new Workspace.
- Delete a Workspace - disconnects all repos from this Workspace and deletes the empty Workspace (does not delete the repos or issues).
Removing a repo from a Workspace
What happens when a repo is removed?
When you remove a repo and choose not to move it into a new Workspace; the remove action reverts the issues in the repository into an "unsorted" state. The repo will still exist in GitHub, but if you try to view that repo in ZenHub in the future, you’ll be prompted to add it to a new or existing Workspace. Repos that belong to another Workspace will not be affected.
What you need to know:
- This impacts all team members that rely on this Workspace. A disconnection takes place for everyone using this Workspace.
- The issues in this repo will become unsorted and placed in a single pipeline next time it is added into a new Workspace. The order of these issues will remain unchanged in other Workspaces.
- If you want to preserve the ordering and pipelines of the Issues, split the repo into a new Workspace instead (see the section below).
- Any cross-repo epic, issue dependencies, and PR <> issue connections will be disconnected.
- When you disconnect a repo, the corresponding issues will be removed from the reports. Consequently, you may notice a change in your reports: change in the averages on the cumulative flow and control chart and lower story point totals in the burndown and velocity report.
How to remove a Repo from a Workspace
You can remove a repo from a Workspace through the Workspace Editor via the sidebar Workspace navigation. Simply hover over the sidebar and select Edit on the Current Workspace.
Click on the three dots next to any connected repo and you’ll see an option to Remove repo.
Splitting a repo into it's own Workspace
What happens when a repo is split?
When splitting a repo, the repo will be disconnected from the current Workspace and moved into its own, brand-new Workspace. All pipeline names, issue order and allocation to the pipelines will remain the same in your new single-repo Workspace.
What you need to know:
- This impacts all team members that rely on this Workspace. A split takes place for everyone using this Workspace.
- Any cross-repo epic, issue dependencies, and PR <> issue connections will be disconnected.
- The release report supports cross-Workspace connections and will have a new section: Not in this Workspace. (The other reports will no longer show issues from the split repo.)
- If the repo belongs to more than one Workspace, it will not be affected in any of the other Workspaces.
How to split a repo into its own Workspace
Enter the Workspace Editor via the sidebar Workspace navigation. Hover over the sidebar and select Edit on the Current Workspace.
Click on the three dots next to any connected repo and you’ll see an option to Split repo into own Workspace .
Deleting a Workspace
If your team no longer needs a Workspace, you can delete it. Deleting a Workspace will not delete the repos or issues within it, but it will remove the Workspace from your sidebar. The repos will become disconnected and go into an “unsorted” state*. Repos that belong to other Workspaces will not be affected.
What you need to know:
- All Workspace deletions are organization-wide and cannot be undone.
- To delete a Workspace you must have push/write permissions to all connected repositories or be the admin of the organization that these repositories belong to in GitHub. Learn more about permissions
- Any cross-repo epic, dependency, issue <> PR connections that relied on this Workspace will be disconnected.
- The next time repos from this Workspace get added to a new Workspace the issue placement will be unsorted.
How to Delete a Workspace
Enter the Workspace Editor via the sidebar Workspace navigation. Hover over the sidebar and select Edit on the Current Workspace.
At the bottom of the page, you’ll see a Delete this Workspace button:
*What’s an ‘unsorted’ state
When you disconnect or delete a workspace, the repo will still exist in GitHub, but if you try to view that repo in ZenHub, you’ll be prompted to add it to a new or existing Workspace first. Repos that belong to another Workspace will not be affected. The issues in this repo will become unsorted and placed in a single pipeline next time it is added into a new Workspace. The order of these issues will remain unchanged in other Workspaces.
Reminder: Deleting a Workspace does not delete the repository nor Issues in the repository; however, it will remove references to this Workspace in any issue event history, not be searchable, nor will the reports be accessible for historical reference.
Unsure which option to select? Get in touch with your use case and we'll walk you through the options!