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.

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 GitHub repositories using the "Add a repo +" option. You'll also want to set a default repository for new issue creation and configure your initial pipeline structure.

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.

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.

To add repositories to your Workspace, use the "Repos" dropdown in the top-left of your Workspace and select "Add repos." Search for the repository you want to connect and use the avatar selector to toggle between different organizations. Once you find the repository you need, confirm the connection.

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.

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 "Repos" dropdown and removing unwanted repositories. Be aware that disconnecting a repository loses all issue prioritization and pipeline placement for issues in that repository.

Splitting Workspaces: As projects grow or team structures change, you may need to separate repositories into focused Workspaces. This helps maintain clear team boundaries and reduces cognitive load by keeping workspaces focused on specific projects or products.

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

Q: Can the same GitHub repository be in multiple Workspaces?

A: 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.

Q: What happens to issue prioritization when I remove a repository from a Workspace?

A: 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.

Q: How do I handle conflicts when multiple teams want different pipeline structures for the same repository?

A: 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.

Q: Why does Zenhub automatically organize issues when I add a repository?

A: 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.

Q: Can I customize how new repositories are organized when added to my Workspace?

A: 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.