delete-missing-labels feature

Author: UltraProdigy

.github/workflows/config-label-sync.yml

@@ -55,11 +55,11 @@ jobs:
         run: |
           git config user.name "github-actions[bot]"
           git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
-          if git diff --quiet -- config/labels.jsonc; then
+          if git diff --quiet -- config/labels.jsonc config/deleted-labels.jsonc; then
             echo "No config changes detected."
             exit 0
           fi
-          git add config/labels.jsonc
+          git add config/labels.jsonc config/deleted-labels.jsonc
           git commit -m "Sync labels config from source repository"
           git remote set-url origin "https://x-access-token:${PUSH_TOKEN}@github.com/${{ github.repository }}.git"
           git push origin "HEAD:${{ github.event.repository.default_branch }}"

README.md

@@ -5,6 +5,7 @@ This repository is a standalone GitHub label management repo for an organization
 Its job is to:
 
 - keep this repo's label config in sync with the labels currently defined on the repo
+- track labels removed from that source config so they can be deleted from synced repositories
 - validate config changes automatically
 - sync the resulting label set across the rest of the organization
 - remove an exact label from issues and pull requests across the filtered repository set
@@ -25,9 +26,10 @@ The normal flow is:
 1. You run `Org-Label-Sync` manually.
 2. It first calls `Config-Label_Sync`.
 3. `Config-Label_Sync` reads the labels on this repository and rewrites `config/labels.jsonc` so the file matches the repo's current labels.
-4. If that file changed, `Config-Label_Sync` commits and pushes the update.
-5. That config change triggers `Validate-Configs`.
-6. `Org-Label-Sync` then checks out the latest default branch, validates the config again, and syncs labels across the organization.
+4. Any labels that were previously managed but are no longer on the source repository are moved to `config/deleted-labels.jsonc`.
+5. If either config file changed, `Config-Label_Sync` commits and pushes the update.
+6. That config change triggers `Validate-Configs`.
+7. `Org-Label-Sync` then checks out the latest default branch, validates the config again, and syncs labels across the organization.
 
 The reverse flow is:
 
@@ -48,6 +50,7 @@ The reverse flow is:
 |       |-- reverse-config-label-sync.yml
 |       `-- validate-configs.yml
 |-- config/
+|   |-- deleted-labels.jsonc
 |   |-- github-default-labels.jsonc
 |   |-- labels.jsonc
 |   |-- properties.jsonc
@@ -67,6 +70,7 @@ The reverse flow is:
     |-- sync-labels.mjs
     `-- lib/
         |-- changelog-utils.mjs
+        |-- config-validation.mjs
         `-- config-utils.mjs
 ```
 
@@ -134,6 +138,20 @@ Example:
 ]
 ```
 
+### `config/deleted-labels.jsonc`
+
+This is the list of labels that should be deleted from synced repositories.
+
+It is normally maintained automatically by `Config-Label_Sync`. When a label existed in `config/labels.jsonc` and is later removed from the source repository, the last managed label spec is moved here.
+
+Each entry uses the same object shape as `config/labels.jsonc`:
+
+- `name`
+- `color`
+- `description`
+
+`Org-Label-Sync` deletes matching label names from target repositories regardless of color or description. If a label appears again on the source repository, `Config-Label_Sync` removes it from `config/deleted-labels.jsonc` and restores it to `config/labels.jsonc`.
+
 ### `config/github-default-labels.jsonc`
 
 This is the list of exact GitHub default labels that can be removed from synced repositories when they are not managed by `config/labels.jsonc`.
@@ -218,8 +236,9 @@ What it does:
 3. Resolves either the configured PAT or a GitHub App installation token
 4. Reads the current labels on the source repository
 5. Rewrites `config/labels.jsonc` so it exactly matches the source repository labels
-6. Validates `config/github-default-labels.jsonc` so exact GitHub default label specs remain well-formed
-7. Commits and pushes the change if the config was updated
+6. Moves any previously managed labels that are missing from the source repository into `config/deleted-labels.jsonc`
+7. Validates `config/github-default-labels.jsonc` so exact GitHub default label specs remain well-formed
+8. Commits and pushes the change if either config file was updated
 
 This workflow is the bridge between "the labels on this repo right now" and "the managed config we sync elsewhere."
 
@@ -242,6 +261,7 @@ Validation includes:
 - JSONC parsing
 - required property checks
 - duplicate label detection
+- deleted-label shape and duplicate-name validation
 - repository filter shape and `useWhitelist` validation
 - duplicate whitelist and blacklist detection
 - invalid colors
@@ -295,9 +315,10 @@ What it does:
 6. Discovers repos in the configured organization
 7. Applies `config/repository-filter.jsonc`, unless `repositories` was provided as a workflow dispatch config override
 8. Creates or updates labels from `config/labels.jsonc`
-9. Deletes labels that exactly match entries in `config/github-default-labels.jsonc` only when the `delete_github_default_labels` workflow checkbox is checked, unless that label name is managed by `config/labels.jsonc`
-10. Optionally deletes any other unmanaged labels only when the `delete_missing` workflow checkbox is checked; exact GitHub default labels are reserved for `delete_github_default_labels`
-11. If at least one target repo changed or would change, writes a changelog and commits it with `[skip ci]`; real runs write to `changelogs/YYYY-MM-DD/`, while preview runs write fake changelogs to `fake-changelogs/YYYY-MM-DD/` and do not apply repository changes
+9. Deletes labels whose names match entries in `config/deleted-labels.jsonc`
+10. Deletes labels that exactly match entries in `config/github-default-labels.jsonc` only when the `delete_github_default_labels` workflow checkbox is checked, unless that label name is managed by `config/labels.jsonc`
+11. Optionally deletes any other unmanaged labels only when the `delete_missing` workflow checkbox is checked; exact GitHub default labels are reserved for `delete_github_default_labels`
+12. If at least one target repo changed or would change, writes a changelog and commits it with `[skip ci]`; real runs write to `changelogs/YYYY-MM-DD/`, while preview runs write fake changelogs to `fake-changelogs/YYYY-MM-DD/` and do not apply repository changes
 
 ### `Remove-Labels`
 
@@ -336,6 +357,7 @@ Each changelog file is created only when a workflow actually changes, or in prev
 
 - created labels
 - updated labels, including changed fields
+- labels deleted by `config/deleted-labels.jsonc`
 - GitHub default labels that were deleted
 - unmanaged labels that were deleted when delete-missing is enabled
 
@@ -363,7 +385,7 @@ That PAT needs enough access to:
 - read and update labels on target repositories
 - read and update labels on the source repository when running `Reverse-Config-Label-Sync`
 - read and update issues and pull requests when running `Remove-Labels`
-- push config updates back to this repository when `Config-Label_Sync` changes `labels.jsonc`
+- push config updates back to this repository when `Config-Label_Sync` changes `labels.jsonc` or `deleted-labels.jsonc`
 - push changelog commits back to this repository when an action changes another repository
 
 For GitHub App auth, create repository secrets whose names match:
@@ -388,6 +410,7 @@ The GitHub App installation must be granted access to this configuration reposit
 ## Safe Defaults
 
 - `labels.jsonc` starts empty until you define or sync labels on this repo
+- `deleted-labels.jsonc` starts empty and is populated when synced labels are removed from the source repository
 - all repos in the org are targeted unless excluded by `repository-filter.jsonc`
 - GitHub default labels are pruned by default when they exactly match `config/github-default-labels.jsonc`; uncheck `delete_github_default_labels` to keep them
 - deleting unmanaged labels is off by default unless you check `delete_missing` when running `Org-Label-Sync`

config/deleted-labels.jsonc

@@ -0,0 +1,12 @@
+// Labels removed from config/labels.jsonc by Config-Label_Sync are moved here.
+// Org-Label-Sync deletes matching label names from selected repositories.
+//
+// Example:
+// [
+//   {
+//     "name": "status: stale",
+//     "color": "ededed",
+//     "description": "No recent activity"
+//   }
+// ]
+[]

scripts/lib/changelog-utils.mjs

@@ -122,6 +122,16 @@ export function renderLabelSyncSection(result) {
     lines.push("");
   }
 
+  const deletedConfigured = renderList(
+    result.deletedConfiguredLabels,
+    (label) => `Deleted configured removed label \`${label.name}\``,
+  );
+  if (deletedConfigured) {
+    lines.push("Deleted labels from deleted-labels config:");
+    lines.push(deletedConfigured);
+    lines.push("");
+  }
+
   const deletedGithubDefaults = renderList(
     result.deletedGithubDefaultLabels,
     (label) => `Deleted GitHub default label \`${label.name}\``,

scripts/lib/config-validation.mjs

@@ -175,28 +175,54 @@ export function validateProperties(properties, options = {}) {
   return validated;
 }
 
-export function validateLabels(labels) {
-  assert(Array.isArray(labels), "config/labels.jsonc must contain an array.");
+function validateLabelSpecs(labels, { configPath, itemLabel }) {
+  assert(Array.isArray(labels), `${configPath} must contain an array.`);
 
   const seen = new Set();
 
   return labels.map((label, index) => {
-    assert(label && typeof label === "object" && !Array.isArray(label), `Label at index ${index} must be an object.`);
-    assert(typeof label.name === "string" && label.name.trim(), `Label at index ${index} is missing a valid name.`);
-    assert(typeof label.color === "string" && /^[0-9a-fA-F]{6}$/.test(normalizeColor(label.color)), `Label "${label.name}" must have a 6-character hex color.`);
+    assert(label && typeof label === "object" && !Array.isArray(label), `${itemLabel} at index ${index} must be an object.`);
+    assert(typeof label.name === "string" && label.name.trim(), `${itemLabel} at index ${index} is missing a valid name.`);
+    assert(typeof label.color === "string" && /^[0-9a-fA-F]{6}$/.test(normalizeColor(label.color)), `${itemLabel} "${label.name}" must have a 6-character hex color.`);
 
     const key = normalizeName(label.name);
-    assert(!seen.has(key), `Duplicate label name detected: "${label.name}".`);
+    assert(!seen.has(key), `Duplicate ${itemLabel.toLowerCase()} name detected: "${label.name}".`);
     seen.add(key);
 
     if (label.description !== undefined) {
-      assert(typeof label.description === "string", `Label "${label.name}" has a non-string description.`);
+      assert(typeof label.description === "string", `${itemLabel} "${label.name}" has a non-string description.`);
     }
 
     return normalizeLabelSpec(label);
   });
 }
 
+export function validateLabels(labels) {
+  return validateLabelSpecs(labels, {
+    configPath: "config/labels.jsonc",
+    itemLabel: "Label",
+  });
+}
+
+export function validateDeletedLabels(deletedLabels) {
+  return validateLabelSpecs(deletedLabels, {
+    configPath: "config/deleted-labels.jsonc",
+    itemLabel: "Deleted label",
+  });
+}
+
+export function assertNoManagedDeletedLabelOverlap(managedLabels, deletedLabels) {
+  const managedByName = new Map(managedLabels.map((label) => [normalizeName(label.name), label.name]));
+  const overlappingLabels = deletedLabels
+    .filter((label) => managedByName.has(normalizeName(label.name)))
+    .map((label) => label.name);
+
+  assert(
+    overlappingLabels.length === 0,
+    `Labels cannot be both managed and deleted: ${overlappingLabels.join(", ")}.`,
+  );
+}
+
 export function validateGithubDefaultLabels(githubDefaultLabels) {
   assert(Array.isArray(githubDefaultLabels), "config/github-default-labels.jsonc must contain an array.");
 

scripts/reverse-config-label-sync.mjs

@@ -8,6 +8,8 @@ import {
   readJsonc,
 } from "./lib/config-utils.mjs";
 import {
+  assertNoManagedDeletedLabelOverlap,
+  validateDeletedLabels,
   validateGithubDefaultLabels,
   validateLabels,
   validateProperties,
@@ -16,6 +18,7 @@ import {
 const workspaceRoot = process.cwd();
 const propertiesPath = path.join(workspaceRoot, "config", "properties.jsonc");
 const labelsPath = path.join(workspaceRoot, "config", "labels.jsonc");
+const deletedLabelsPath = path.join(workspaceRoot, "config", "deleted-labels.jsonc");
 const githubDefaultLabelsPath = path.join(workspaceRoot, "config", "github-default-labels.jsonc");
 
 const validateOnly = process.argv.includes("--validate-only");
@@ -176,12 +179,14 @@ async function main() {
     defaultSourceRepository: process.env.GITHUB_REPOSITORY ?? "",
   });
   const labels = validateLabels(await readJsonc(labelsPath));
+  const deletedLabels = validateDeletedLabels(await readJsonc(deletedLabelsPath));
+  assertNoManagedDeletedLabelOverlap(labels, deletedLabels);
   const githubDefaultLabels = validateGithubDefaultLabels(await readJsonc(githubDefaultLabelsPath));
   const repository = process.env.SOURCE_REPOSITORY ?? properties.sourceRepository;
   assert(repository, "SOURCE_REPOSITORY or properties.sourceRepository is required.");
 
   console.log(
-    `Loaded ${labels.length} managed labels and ${githubDefaultLabels.length} exact GitHub default label specs for ${repository}.`,
+    `Loaded ${labels.length} managed labels, ${deletedLabels.length} deleted labels, and ${githubDefaultLabels.length} exact GitHub default label specs for ${repository}.`,
   );
 
   if (validateOnly) {

scripts/sync-config-labels.mjs

@@ -1,16 +1,18 @@
 import path from "node:path";
 import {
+  normalizeName,
   assert,
   normalizeColor,
   normalizeDescription,
   readJsonc,
   writeJsoncPreservingHeader,
 } from "./lib/config-utils.mjs";
-import { validateGithubDefaultLabels, validateProperties } from "./lib/config-validation.mjs";
+import { validateDeletedLabels, validateGithubDefaultLabels, validateLabels, validateProperties } from "./lib/config-validation.mjs";
 
 const workspaceRoot = process.cwd();
 const propertiesPath = path.join(workspaceRoot, "config", "properties.jsonc");
 const labelsPath = path.join(workspaceRoot, "config", "labels.jsonc");
+const deletedLabelsPath = path.join(workspaceRoot, "config", "deleted-labels.jsonc");
 const githubDefaultLabelsPath = path.join(workspaceRoot, "config", "github-default-labels.jsonc");
 
 async function githubRequest(token, method, apiPath) {
@@ -58,6 +60,27 @@ function toManagedLabels(labels) {
     .sort((left, right) => left.name.localeCompare(right.name));
 }
 
+function mergeDeletedLabels(previousManagedLabels, currentManagedLabels, deletedLabels) {
+  const currentKeys = new Set(currentManagedLabels.map((label) => normalizeName(label.name)));
+  const nextDeletedByName = new Map();
+
+  for (const label of deletedLabels) {
+    const key = normalizeName(label.name);
+    if (!currentKeys.has(key)) {
+      nextDeletedByName.set(key, label);
+    }
+  }
+
+  for (const label of previousManagedLabels) {
+    const key = normalizeName(label.name);
+    if (!currentKeys.has(key)) {
+      nextDeletedByName.set(key, label);
+    }
+  }
+
+  return [...nextDeletedByName.values()].sort((left, right) => left.name.localeCompare(right.name));
+}
+
 async function main() {
   const token = process.env.CONFIG_LABEL_SYNC_TOKEN ?? process.env.GITHUB_TOKEN;
   assert(token, "CONFIG_LABEL_SYNC_TOKEN or GITHUB_TOKEN is required.");
@@ -69,14 +92,18 @@ async function main() {
   const repository = process.env.SOURCE_REPOSITORY ?? properties.sourceRepository;
   assert(repository, "SOURCE_REPOSITORY or GITHUB_REPOSITORY is required.");
 
+  const previousManagedLabels = validateLabels(await readJsonc(labelsPath));
+  const deletedLabels = validateDeletedLabels(await readJsonc(deletedLabelsPath));
   const githubDefaultLabels = validateGithubDefaultLabels(await readJsonc(githubDefaultLabelsPath));
   const repositoryLabels = await getAllLabels(token, repository);
   const managedLabels = toManagedLabels(repositoryLabels);
+  const nextDeletedLabels = mergeDeletedLabels(previousManagedLabels, managedLabels, deletedLabels);
 
   await writeJsoncPreservingHeader(labelsPath, managedLabels);
+  await writeJsoncPreservingHeader(deletedLabelsPath, nextDeletedLabels);
 
   console.log(
-    `Synced ${managedLabels.length} managed labels from ${repository} into config/labels.jsonc. Source labels take precedence over ${githubDefaultLabels.length} exact GitHub default label specs.`,
+    `Synced ${managedLabels.length} managed labels from ${repository} into config/labels.jsonc and tracked ${nextDeletedLabels.length} deleted labels in config/deleted-labels.jsonc. Source labels take precedence over ${githubDefaultLabels.length} exact GitHub default label specs.`,
   );
 }