Managing Workspaces
Complete guide to creating, customizing, and managing Zenhub workspaces for effective team collaboration
What is a Workspace?
A Workspace is how you organize GitHub repositories and issues in Zenhub. Think of it as a customized project view that brings together all the repositories your team needs to work effectively. With Workspaces, you can connect multiple GitHub repositories—even across different organizations—into a single, unified view.
Workspaces provide a centralized view of issues across multiple repositories, allowing teams to see all their work in one place. Each team can maintain their own pipelines and workflows without disrupting other teams working from the same repositories. You'll also get shared reporting and analytics across all connected repositories, plus flexible permissions to control collaboration levels.
We recommend creating a separate workspace for each team in your organization, eg. "Engineering Team A", "Engineering Team B", "Marketing Team", "QA Team", etc... You can then ensure work flows from team-to-team using the Workflows feature.
Creating Your First Workspace
When you first join Zenhub, you'll need to create a Workspace to begin organizing your work. You can create a Workspace through the Zenhub web app or the browser extension.
To create a Workspace in the web app, click the "Create new Workspace" button in the Workspace navigator located in the left sidebar. Give your Workspace a unique name and description, then add your issue sources.
If you prefer to work within GitHub, you can create a Workspace through the browser extension. First install the Zenhub extension for Chrome or Firefox, then navigate to one of your GitHub repositories. Click the Zenhub tab within GitHub and follow the prompts to create your first Workspace.
NOTE: Workspace names must be unique across all of Zenhub and are case-insensitive.
Workspace Issue Sources
Workspaces are made up of one or more issue sources. Repositories are where your issues live. At the moment Zenhub Workspaces support two different types of issue sources: GitHub repositories and other Zenhub Workspace (aka. Zenhub Repositories). You can add repositories to your Workspace using the "Add Issue Source" button.
Multi-Repository Workspaces
Software projects often span several repositories, and your Workspace should reflect this reality. You can connect repositories together to get a comprehensive view of your project.
When adding repositories with existing pipelines, you'll see a merge preview where you can organize your workflow. You can drag and drop pipelines to match your team's preferred structure, merge similar pipelines such as combining "QA" and "Review" into one pipeline, and rename pipelines to match your team's terminology.
Automatic Issue Organization
When you connect an existing GitHub repository with established issues, Zenhub automatically organizes them into appropriate pipelines based on GitHub metadata rather than dumping everything into a single pipeline. This automatic placement analyzes issue data to create a logical starting point for your board.
Issues older than 90 days are placed in the Icebox pipeline, as these are likely stale or archived work items. Issues updated within the last 30-90 days go to Product Backlog, representing recent work that isn't currently active. Issues assigned to open GitHub milestones are placed in Sprint Backlog, indicating planned work with defined timelines. Open pull requests and their linked issues go directly to In Progress, reflecting active development work.
This automatic organization saves significant setup time and prevents the overwhelming experience of having hundreds of unsorted issues in your backlog. You can always adjust the placement afterward, but the intelligent defaults provide an excellent starting point that reflects your repository's actual state.
TIP: Before merging repositories, discuss the pipeline structure with your team. Once merged, disconnecting a repository will lose all issue prioritization.
Navigating Your Workspace
Zenhub provides several tools to help you move efficiently between workspaces and find the views you need.
Use the Workspace navigator in the left sidebar to switch between different workspaces. Click the star icon next to frequently-used Workspaces to mark them as favorites, making them appear at the top of your workspace list. The quick switcher provides fast access to recent Workspaces you've visited.
Create saved views to preserve custom board configurations with specific filters. These views let you focus on relevant subsets of work without repeatedly applying the same filters. You can create saved views for individual team members' work, specific sprints or milestones, particular issue types or labels, and cross-repository project views.
Workspace Maintenance
Regular workspace maintenance keeps your project views organized and relevant as your work evolves.
Removing repositories: Disconnect repos no longer needed by using the "Issue Sources" section of the "Edit Workspace" page. From here you remove unwanted repositories. Be aware that disconnecting a repository loses all issue prioritization and pipeline placement for issues in that repository.
Deleting Workspaces: Permanently remove unused Workspaces through workspace settings when they no longer serve your team. This cleanup prevents workspace clutter and makes it easier to find active projects.
Archive management: Handle archived GitHub repositories appropriately by either removing them from active workspaces or creating dedicated archive workspaces if you need occasional access to historical project data.
FAQ
Can the same GitHub repository be in multiple Workspaces?
Yes! The same repository can be added to multiple Workspaces, allowing different teams to work with the same issues using their preferred workflows and pipeline structures.
What happens to issue prioritization when I remove a repository from a Workspace?
All issue prioritization and pipeline placement for that repository will be lost when disconnected. Make sure to discuss with your team before removing repositories from Workspaces.
How do I handle conflicts when multiple teams want different pipeline structures for the same repository?
Create separate Workspaces for each team and use Workflows to automate issue movement between them. This allows each team to maintain their preferred workflow while keeping coordination automated.
When should I use GitHub Repository vs. Zenhub Repository (Zenhub Workspace) issue sources?
If your team is already using GitHub Repositories for tracking your issues -- use GitHub Repositories. This will bring all your existing GitHub Issues into the Zenhub Workspace so you can see them on the board and in the reports. Issues in GitHub Repositories live in GitHub and make use of all the GitHub features like label management, release tracking, pull request connections, etc... However, one drawback of GitHub Repositories is that issues are tied to a specific code repository.
For teams that want to share and track work across different code repositories, Zenhub Repositories are ideal. Zenhub Repositories are not linked to a specific code repository and instead are global to your entire Zenhub Organization. Any issues inside Zenhub Repositories can be viewed in any Zenhub Workspace without being restricted by tight GitHub code repository permission controls. Note that Zenhub Repositories can only contact Zenhub Issues (not GitHub Issues).
In short -- we reconnect GitHub Repository issue sources for engineering & code tasks, and Zenhub Repository issue sources for non-engineering tasks (like marketing, design and business objectives).
The GitHub issues in my workspace are stale or out-of-date from what GitHub is showing. How does Zenhub sync data from GitHub?
Zenhub has a robust data synchronization engine that ensures GitHub data is kept in-sync with what's shown in Zenhub. Data is synced in real-time and when a change happens in GitHub it will usually get reflected in Zenhub within a few seconds. Zenhub does this for you automatically and you shouldn't need to do anything to guarantee fast and reliable updaates.
In rare instances, it's possible there may be longer delays or broken data connections between Zenhub and GitHub. This can happen if there are GitHub outages, misconfigured GitHub permissions, or heavy traffic on either GitHub or Zenhub servers. If you're seeing data in Zenhub that doesn't match what you're seeing in GitHub you can force a manual data re-sync for the impacted GitHub repository.
Navigate to the "Workspace Settings" page, then find the GitHub Repository issue source that's having issues. Click the "..." menu and select "Force re-sync". This will kick off a background job to:
Ensure the necessary GitHub repository webhooks are setup and working
Re-sync the latest GitHub issue and pull request data
Re-sync the latest GitHub assignees and label data
Remove any deleted GitHub issues
Note that although this will typically happen immediately, during heavy system load it can take up to 5 minutes before the job fully complete.
Why does Zenhub automatically organize issues when I add a repository?
Automatic organization prevents hundreds of unsorted issues from overwhelming your backlog. Zenhub analyzes issue age, update dates, milestones, and PR status to create logical starting positions that reflect your repository's actual state.
Can I customize how new repositories are organized when added to my Workspace?
The automatic organization follows standard patterns, but you can immediately adjust issue placement after connection. Pipeline merge previews also let you organize the structure before finalizing the repository connection.
Can I download all of the issues on a board to a .csv file?
We currently don't have the option to export tickets to an external file. But you have options!
If you're experienced with API's, you can leverage Zenhub's GraphQL API to gather the data you need. Documentation on our API can be found here: https://developers.zenhub.com/
Alternatively, you could add any required issues to a Release, then download the Release burnup as a .csv file.