diff --git a/building/config.json b/building/config.json index 85726175..b19ba555 100644 --- a/building/config.json +++ b/building/config.json @@ -673,6 +673,12 @@ "path": "building/tracks/ci/workflows/configlet.md", "title": "configlet workflow" }, + { + "uuid": "fd512058-4525-4e14-a912-9df870025989", + "slug": "tracks/ci/workflows/sync-labels", + "path": "building/tracks/ci/workflows/sync-labels.md", + "title": "Sync labels workflow" + }, { "uuid": "191b0fa1-96e2-48a6-ad2e-c34f57443799", "slug": "tracks/ci/migrating-from-travis", diff --git a/building/tracks/ci/workflows.md b/building/tracks/ci/workflows.md index 4e81eebd..772bef4c 100644 --- a/building/tracks/ci/workflows.md +++ b/building/tracks/ci/workflows.md @@ -23,7 +23,7 @@ You should thus not manually change their contents. ### General workflows -- `sync-labels.yml`: automatically syncs the repository's labels from a `labels.yml` file +- [`sync-labels.yml`](/docs/building/tracks/ci/workflows/sync-labels): automatically syncs the repository's labels from a `labels.yml` file ### Track-specific workflows diff --git a/building/tracks/ci/workflows/sync-labels.md b/building/tracks/ci/workflows/sync-labels.md new file mode 100644 index 00000000..1c3f501c --- /dev/null +++ b/building/tracks/ci/workflows/sync-labels.md @@ -0,0 +1,21 @@ +# Sync labels workflow + +The sync labels workflow is defined in the `.github/workflows/sync-labels.yml` file. +The goal of this workflow is to add/update/delete the repository's [GitHub labels](https://docs.github.com/en/issues/using-labels-and-milestones-to-track-work/managing-labels). +The labels themselves are defined in the `.github/labels.yml` file. +Whenever the `.github/labels.yml` file changes, the sync labels workflow will automatically update the repository's labels. + +## Customizing labels + +The labels defined in `.github/labels.yml` come in two forms: + +- Shared labels: these are labels used by _all_ Exercism repositories, and they're defined in the [org-wide-files repo](https://github.com/exercism/org-wide-files/blob/main/global-files/.github/labels.yml) +- Track-specific labels: these are defined in an `.appends/.github/labels.yml` file + +To add track-specific labels, you'll need to add them to the `.appends/.github/labels.yml` file (see [this example](https://github.com/exercism/python/blob/main/.appends/.github/labels.yml)). +Once you've merged the changes to `main`, a pull request will automatically be opened to change the `.github/labels.yml` file. +After merging that PR, the labels will be automatically updated (see description above). + +```exercism/caution +Never manually edit the `.github/labels.yml` file, as those changes will be overwritten the next time labels are synced. +```