How we use GitHub Projects (Beta)

All issues should be created within a single repo

We create all issues within the sourcegraph/customer repository.

Many GitHub features (exp. Milestones and Labels) work only within a single repo. If the issues span across multiple repositories, we need to duplicate the label creation and cannot group all of them under a single milestone. The sourcegraph/customer repository is private, so we do not risk exposing any private data in the description or comments of the issues.

Hierarchy in GitHub projects

We use the Milestone -> Epic -> Issue hierarchy.


To track progress on bigger initiatives with potentially an expected launch date and cross-team dependencies, we use GitHub Milestones. Milestones support title, description, and the optional due date. We can easily assign issues to milestones and filter them down on our project board or use the milestone view, which supports additional progress visualization.

For milestones to work, we need to keep all issues within the single repository as milestones are restricted to the single repo.


We introduce the concept of epics to group issues together that belong to a single initiative or problem space. For example, Managed SMTP on the Cloud or MI v1 -> V1.1 migration. This allows us to better track progress within the given initiative.

Unfortunately, GitHub does not support epics as a separate entity, so we need to implement custom workarounds to have epics.

How to create epic

  • Create a new issue with EPIC: <epic title> naming convention
  • Add the <epic title> option to the Cloud GitHub project EPIC filed in settings
  • Add the cloud-epic label (required for filtering GH project views)
  • Add<epic title>%22 to the epic issue (this will link to a view with all issues assigned to this epic)

How to add an issue to an epic

To add issues to the epic, select the epic title from the EPIC field dropdown in the Cloud team GitHub project.


Every task that the Cloud team is working on should have a GitHub issue. This will allow the team to avoid creating shadow work and provide transparency on where we invest the team’s time.

All requests for help should have an issue assigned.

While we can answer questions from other teams on #cloud slack channel, if the question turns out to be an actual request for performing an action and the common-sense rule from above does not apply, we should ask the requestor for a GitHub issue.

Cloud team GitHub project custom fields

GitHub project beta supports custom fields that can be added to the list views. This provided us with additional layers of sorting, filtering, and categorization. Below is the list of the fields the Cloud team uses right now.

Field nameData typePurpose
StatusEnum - selectCurrent status of the issue when it comes to its execution
EPICEnum - selectAdd the issue to epic
SLADateAssign the SLA for MI requests and P1
EstimateEnum - selectEstimate the effort and complexity of the issue with a single developer days
MilestoneGH milestoneAssign the issue to milestone
GroomingBooleanFlag that the issue is scheduled for a weekly grooming cycle
ComponentEnum - selectExperimental - categorize issues based on the service/component within the system

Cloud team GitHub project board views

View NamePurpose
Backlog viewAll issues except the ones with no status and the status Done are grouped by the status. This view is best used for a general backlog overview, refining, and prioritization.
Kanban boardA board view for everyday IC workflow. Contains issues from Up next to Done
New ItemsThe view with all new issues without status that requires triaging and prioritization
Epics viewThe view containing all the epics grouped by milestones
Request for help viewThe view containing all requests for help from Customer Engineering & Support, including P1s and P2s group by status
Manage instance creation requestsThe view containing special type of mange instance requests with SLAs created for auditing requirements
Manage instance tear-down requestsThe view containing special type of mange instance requests with SLAs created for auditing requirements
Postmortem Action Items viewThe view containing all issues that were created as post-incident action items owned by the Cloud team grouped by status
Grooming viewThe special view used to list all issues that are part of the current [grooming cycle](
All issues viewThe special view used to filter down issues by epic - a link to this view is added to every EPIC type issue

Issue status and its meaning

The table below contains all the statuses that are currently added to the Cloud team GitHub project.

No statusNew issue that requires triaging - default status for all new issues added to the project
BlockedThe issue has a blocker that prevents its execution. The blocker should be clearly defined in the issue comments
BacklogTriaged issues that should be priorities and groomed to be ready for implementation. The Backlog should be prioritized, with the most important issues at the top of the list
Up nextGroomed issues are ready for implementation. Can be picked up by any Cloud engineer as the next task
Waiting for feedbackDevelopment work is completed, and the issue is waiting for review from the rest of the Cloud team or an issue requestor
DoneCompleted work that is delivered/shipped to production