Adding issues from other organisations into Github Projects

Let's talk about how you can add issues from other organisations into your Github Project

Jun 2018
Updated: Apr 2023
1062 words
Productivity

Github allows you to add issues from other repositories and organisations into your Github project, giving you one place where you can view all the issues you have to work on. We’ve been playing with using it to view all your development tasks.

We use Github as our code repository for 90% of our projects, so we’ve decided to go all in and do project management with Github. The biggest perceived issue I had in my head with using Github Projects over say something like Trello is that a Project is linked to an organisation.

We work with clients who have their own Github organisations, so I thought we couldn’t manage everything in one board. I was wrong and in this article I will show you how you can have one view for everything, with only a small amount of manual action.

Github Projects

If you haven’t used Github Projects before they are a kanban board view for Github Issues.

They are available for free for Organisations, these are what Github calls teams.

You can access the boards view from https://github.com/orgs/{YOUR_ORG}/projects

Github Projects Index Page — A view of our Github Projects index page

We just have the one Project, which gives us an overview of all the development tasks we currently need to perform. There doesn’t appear to be an upper limit on how many projects you can have.

Our project has the following columns:

To Do
Priority list
Doing
Done
Done by date (e.g 2018-06-22)

Github provides a mechanism to automatically move issues into relevant columns based on how you’ve set them up. I’m not going to go into exactly how we use each column, that is another article for another day!

Github Projects Show Page — A view of our Github project page

By default any repository under the organisation can add their issues into a particular project. This is how we generally manage our work, we create issues against our repositories, which will add the issue into “To Do”, it will be prioritised and only these tasks get worked on.

This is amazing, suddenly we can see across repositories and really see what is the highest priority ticket that needs worked out. We also get a much better idea of what type of workload we have on.

What I didn’t think we could see (and why I got excited enough to write this article!) is issues from other organisations. As contractors we end up working for lots of clients, many of whom already have their repositories and organisations in Github. It would be brilliant if we could somehow incorporate these issues into our project view.

Adding issues from other Github organisations

As well as being able to track issues, Github Projects have the ability to track arbitrary notes. These are small little markdown enabled text areas that you can later convert into issues.

How we were initially going to tackle adding issues from other Github organisations was to copy and paste the URL as a note. Our thinking behind this was that the URL itself would expose the client and the project name.

I’m so glad we didn’t decide to try and add anything more, because just adding the URL to a note is exactly what you need in order to be able to “import” the issue into your project.

I say “import” and not import, because all that is happening is a reference to the issue is stored.

The issue doesn’t get updated to say it is linked to your project, but your project can now see the issue, including information like who is assigned to it. It also shows the organisation and repository that the issue belongs to.

How to add an issue from another repository in github — An example gif of how pasting an issue from another organisation automatically creates a reference in your project

Adding extra information

You might want to add additional information that makes sense in the context of your project but wouldn’t be appropriate to add to the issue. You can write your note and include a link. Github Projects will expand the link into the same box we had before, in my opinion this doesn’t look as seamless as the link by itself, which is why I prefer adding the link by itself as a first point of call.

Github Projects edit note view — An example of editing a note with a link to another issue inside it

Github Projects note with attached issue — The result of the above example once it has been saved, note how much space it takes up

Adding issues from other sources

By this point we can easily manage Github related issues in one place, but what if you have some issues in Bitbucket or Zendesk or somewhere?

We had to work out exactly this issue, some of our projects live in Bitbucket and it would be amazing if we could have one view for all our issues.

What we decided to do is use the fact that notes in Github Projects can contain markdown and have started adding the following notes.

Project Name - [Issue Name](http://issuetracker.com/my-issue)

@user_responsible

Unfortunately plain notes cannot be assigned to someone, so we just manually tag the person assigned at the end of the note.

Once an issue is closed it needs to be both dragged across into your “done” column of choice in your Github Project and also closed on the system the issue lives.

Example of a note linking to an issue in a different issue tracker

We’re still learning this stuff

This is all very new to us and if you have any strong thoughts or feelings on Github Projects and how to use them to manage across multiple repositories/organisations/issue trackers then we would love to hear your thoughts in the comments.

Please do share this with your project manager friends because I think this could be useful for them to know.