Software projects often span across several GitHub repositories, so naturally, your task boards and reports should too!
Using ZenHub, you can connect repositories together – even across GitHub organizations – to get a bird's eye view into everything going on with your software projects. With advanced filters, you can drill down to see only what you need.
Note: Only once you connect repositories into a Multi-Repo Board can you track them together in reports – like velocity and burndown charts – and other features like multi-repo epics. It all starts on the task board.
How to connect GitHub repositories
Connecting repositories is easy. First, navigate to the first repository you want to connect. Visit the Board, click Repositories (at the top of the Board), then select Merge another repository.
Next, it's time to set up the structure of this new Multi-Repo Board. You'll be presented with a preview screen where you can drag and drop pipelines to determine how they will be merged. You can always fine-tune these settings later.
Let's say you have two pipelines: “QA” and “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, click Merge to finish.
When you merge repositories together, their milestones can merge too – which makes it easy to track and filter them! Currently, both milestones must be exactly the same to merge together as one. Otherwise, they'll appear separately in your reports and task boards. That means they must have the same:
- Start and end date
As long as the above two conditions are met, you can successfully merge milestones before or after you connect task boards.
A well-organized task board can help you uncover bottlenecks faster and provide more information for other stakeholders on the team. While the default board structure is a great starting point for any project, you should consider customizing it to suit your workflow.
When thinking about how to customize your task boards, take an audit of your team's workflow. Look at your boards and ask yourself these questions.
- Does this structure contain only what we need, and nothing more? Could my boss look at this and understand everything she needs to about the project?
- Is every important stakeholder represented? Can someone in design, marketing, or QA look at this board and know exactly where his or her help is needed?
- Are we missing any repeating stages? Think about how your team builds products. It's all about keeping issues flowing across the board. If you have a QA department, for example, you might need a “Ready for QA” pipeline.
- Is “Done” really done? And does my team know and understand our definition of Done? This often-missed step is a crucial part of any agile project.
Pull requests usually relate to at least one GitHub issue, so it makes sense you'd want to track them together as one unit through the development process. Attach pull requests to their corresponding issue, then track them together on your advanced task boards.
A Workflow For Tracking GitHub Issues and Pull Requests
Automate your workflow by first assigning a default pipeline for submitted pull requests when you're creating the PR. This will automatically tell the ZenHub board which pipeline the pull request should be moved to when submitted. This workflow is great to automate small tasks and save time keeping your tasks up-to-date without having to worry about spending time after your work is done.
When the pull request is still open you're able to connect an issue to it. Use the Connect with an issue button below the conflicts confirmation section. You'll be able to connect to any issue that lives in your ZenHub board, including those that are cross-repo (as long as the repos are merged into the same board).
Once connected, an audit trail in both the pull request and issue will be created to provide visability to your team. Your issue will now also be pulled to the same pipeline as the pull request.
Leveraging this connection alongside the default pipeline for pull requests means you're able to automate task updates! The pull request will be nested on the issue on the board.
If a connected issue is closed, don't worry – the pull request won't automatically merge. It'll stay where it is on the Board, and will disconnect from the closed issue. Similarly, if a PR is merged but its issue is not closed, they will remain connected (and the PR will reflect the new merged state.)
- A productivity-boosting workflow for Scrum epics in GitHub