openedx org-wide labels

As of June 2023, this is done!

See for details.

Older links:




We would like to have a standard set of labels available in every repo so that it’s easier to:

  • groom issues in a standard way

  • organize issues on a board across different repositories

  • find issues applicable to beginners/newcomers

We need to agree on two things:

  1. Where to store the cross-repo labels

  2. Which cross-repo labels to start out with (can always be expanded later)

Note: In addition to the cross-repo labels proposed here, repositories will still be able to define their own local labels in the old way (the GitHub repo settings UI). Those labels will not be affected unless they conflict with the cross-repo label names.

Current state

In GitHub’s architecture, labels are managed per-repo, so it takes some work to synchronize them across repos.

We currently keep cross-repo labels in three four places:

  • GitHub’s org-wide default labels.

    • Unfortunately, these only apply to new repos. Updating them will not fix labels any existing repo. As such, most repositories do not have all the labels listed there.

    • Also unfortunately, there does not seem to any programmatic way to query or update these default labels. This means that org-wide default labels cannot be kept in sync with repos, so this path is a dead end for us.

  • The EnsureLabels repo check which, when run, ensures that a defined set of labels exist across many repositories. So far, this has been working well for us.

    • The check is smart: if a label exists in a repo with slight differences (different casing, missing or extra emoji/spaces/dashes, different color), the label will be updated to match the version in the repo check.

    • However, it doesn’t sync label descriptions, although that’d be easy to fix.

    • The set of labels is hard-coded into repo_checks, so it is pretty hard to find for anyone who isn’t in the know.

  • The OSPR bot’s labels.yml file. The bot has historically added these labels, as needed by the OSPR workflow.

    • The file is in a private repo.

    • It’s not clear which labels are used, or if the OSPR bot even still manages labels.

  • The DEPR automation workflow, which specifically adds the DEPR label to a repository if it’s missing.

1. Proposal: Store labels in one central place

This will be implemented by:

  1. Remove extraneous sources of cross-repo labels.

    1. Delete all the repository default labels from the openedx org’s settings.

    2. Remove the labels from the OSPR bot repo.

    3. Remove the DEPR automation step that adds the DEPR label.

  2. Add support for syncing label “descriptions” to EnsureLabels This should be very easy.

  3. Either:

    1. Store the labels in a new labels.yml file in the same directory as Change EnsureLabels to pull labels from the json file.

      • Going forward, cross-repo labels would be managed by editing labels.json and re-running EnsureLabels.

    2. Change EnsureLabels to pull the labels via the API from one central repository: .github.

      • Going forward, cross-repo labels would be managed by editing the labels via the repo settings of .github and re-running EnsureLabels.

      • The benfit of this is that it’d be easier for non-coders to manage cross-repo labels. The drawback of this is that changes to our cross-repo labels would not be version-controlled.

  4. Add a step to tCRIL’s “new repository” playbook: Execute repo_checks so that the new repository’s setting matches our standards, including its list of labels.

2. Proposal: List of starter labels


Description – one brief line that will be shown in the GitHub UI

Notes are in italics


Description – one brief line that will be shown in the GitHub UI

Notes are in italics

good first issue

Good for newcomers

help wanted

Ready to be picked up by anyone in the community

🗺️ epic

Large unit of work, consisting of many tasks

🌎 initiative

Huge unit of work, consisting of multiple epics


Work that must be done for platform health


Something isn't working


Pre-work to determine if idea is feasible


Update or improvement to an existing feature


Further information is requested from the author

Deleted as it seems that this is no longer used for intended purpose (indicating that the triager has a question for the author). Some issues use it to indicate “discovery” but we should just use the discovery label for that. We can always add this label back later.


Condition that must be met for a project or MVP

I’ve removed this from the list as it seems unused.


Addition of new functionality


Proposal for deprecation & removal. See OEP-21


This will not be worked on


This issue or pull request already exists

waiting on author

PR reviewers are waiting on the author to answer questions, fix tests, etc.

Waiting for the author to respond to change requests, feedback, failing tests, etc. Usually this label is used for PRs in board statuses other than “Waiting for Author” (e.g. the pull request is “In Eng Review” column on the board, but the author needs to address review feedback).


PR author has been unresponsive for several months

Used when the author has been unresponsive for several months. Typically author will be told “we might need to close this due to inactivity” and if there’s still no response we close it a couple weeks later.


PR was closed because the author abandoned it

Closed due to PR being abandoned. Typically used after a PR has been abandoned and labeled as “inactive.”

needs test run

Author’s first PR to a repository, awaiting test authorization from tCRIL

This means an author has not contributed to a particular repo before and needs authorization to be able to run tests on the PR. Currently, test authorization is handled by tCRIL.

core contributor

PR author is a Core Contributor to this repository (manually added)

Currently manually applied on the Contributions board to flag to project managers that a CC is the author.


PR author is not from tCRIL or 2U

Automatically added by bot to PRs coming from the community (not tCRIL or 2U).

blocked by other work

PR cannot be finished until other work is complete

Notating that the PR is blocked. It should say in the PR why the work is blocked (e.g. waiting to merge a related PR first).

changes requested


PR reviewers are waiting on author to apply feedback

A reviewer or reviewers have taken a look at the PR and requested the author make changes.

Deleting; we will use “Waiting on Author” instead. We should notify Michelle and Tim when this change happens so that they can update the board.

product review

PR requires product review (= it won’t be merged without review and approval from a product manager).

Jenna Makowski / Ryan O’Connell will add this label to PRs labeled “open-source-contribution” that require Product Review.

Reference: Current cross-repo labels

Repo defaults, from openedx org settings:

Ensured labels, from

{ ":hammer_and_wrench: maintenance": "169509", "waiting on author": "bfd6f6", "inactive": "ff950a", "closed-inactivity": "dbcd00", "needs test run": "f5424b", "good first issue :tada:": "43dd35", }

Labels added by the OSPR bot:

architecture review: # Not used currently color: ffb6c1 awaiting prioritization: color: b7e687 blocked by other work: color: ffa500 changes requested: color: 76a4e3 community manager review: color: ffea45 engineering review: color: 90d946 merged: color: 056608 needs triage: color: b7b7b7 open edx community review: color: 00a7a7 product review: color: c97bf7 rejected: color: a9a9a9 waiting on author: color: bfd6f6 # Other Labels (can be added independently from statuses) blended: color: 6b360f cc-reviewer: color: 5aa17f core committer: color: aaf0d1 open-source-contribution: color: f0f0f0