feat: implement stale issue detector (SE-3-03)

Copilot · DeveloperAlly · Copilot · commit 96b870361f98 · 2026-03-10T15:43:42.000Z
Co-authored-by: DeveloperAlly &lt;12529822+DeveloperAlly@users.noreply.github.com&gt;
diff --git a/.github/workflows/docs-v2-issue-indexer.yml b/.github/workflows/docs-v2-issue-indexer.yml
@@ -114,7 +114,7 @@ jobs:
                 repo,
                 title: INDEX_TITLE,
                 body: placeholderBody,
-                labels: [TARGET_LABEL],
+                labels: [TARGET_LABEL, 'status: pinned'],
               });
               indexIssue = created.data;
               console.log(`Created docs-v2 issue index #${indexIssue.number}`);
diff --git a/.github/workflows/issue-auto-label.yml b/.github/workflows/issue-auto-label.yml
@@ -36,6 +36,7 @@ jobs:
               'docs-v2': { color: '1d76db', description: 'Livepeer docs v2 issue scope' },
               'help wanted': { color: '008672', description: 'Community help requested' },
               'status: needs-triage': { color: 'fbca04', description: 'Needs initial maintainer triage' },
+              'status: pinned': { color: 'e4e669', description: 'Pinned issue; exempt from stale detection and auto-close' },
               'type: bug': { color: 'd73a4a', description: 'Broken behavior or incorrect result' },
               'type: enhancement': { color: 'a2eeef', description: 'Improvement or new capability request' },
               'type: documentation': { color: '0075ca', description: 'Documentation issue or request' },
@@ -66,6 +67,8 @@ jobs:
               'kind: navigation-structure': { color: '5319e7', description: 'Docs page issue subtype: structural/navigation issue' },
               'scope: page': { color: '1d76db', description: 'Issue scoped to a specific docs page' },
               'status: needs-info': { color: 'd4c5f9', description: 'More detail needed from reporter' },
+              'status: stale': { color: 'aaaaaa', description: 'No activity for 60+ days; will be closed if not updated' },
+              'status: autoclosed': { color: '666666', description: 'Automatically closed after extended inactivity' },
             };
 
             const escapeRegex = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
diff --git a/.github/workflows/stale-issue-detector.yml b/.github/workflows/stale-issue-detector.yml
@@ -0,0 +1,75 @@
+name: Stale Issue Detector
+
+on:
+  schedule:
+    - cron: '0 3 * * *'  # Daily at 03:00 UTC
+  workflow_dispatch:
+
+permissions:
+  issues: write
+
+concurrency:
+  group: stale-issue-detector
+  cancel-in-progress: true
+
+jobs:
+  stale:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Mark and close stale issues
+        uses: actions/stale@v9
+        with:
+          # Label applied when an issue becomes stale
+          stale-issue-label: 'status: stale'
+
+          # Label applied when a stale issue is closed
+          close-issue-label: 'status: autoclosed'
+
+          # Days of inactivity before an issue is marked stale
+          days-before-issue-stale: 60
+
+          # Days after being marked stale before the issue is closed
+          days-before-issue-close: 14
+
+          # Comment posted when an issue is marked stale
+          stale-issue-message: >
+            This issue has been automatically marked as stale because it has not had
+            activity in the last 60 days. It will be closed in 14 days unless updated
+            or a maintainer removes the `status: stale` label.
+
+
+            If this issue is still relevant, please:
+
+            - Add a comment with any new information or context
+
+            - Remove the `status: stale` label to reset the inactivity timer
+
+
+            Thank you for contributing to Livepeer Docs!
+
+          # Comment posted when a stale issue is closed
+          close-issue-message: >
+            This issue has been automatically closed because it remained stale for
+            14 days with no further activity. If the problem is still present, please
+            open a new issue with up-to-date details.
+
+          # Labels that prevent an issue from being marked stale
+          exempt-issue-labels: >
+            status: pinned,
+            priority: critical,
+            priority: high,
+            classification: urgent,
+            classification: high,
+            status: in-progress,
+            status: needs-triage,
+            status: needs-info
+
+          # Only operate on issues (not pull requests)
+          days-before-pr-stale: -1
+          days-before-pr-close: -1
+
+          # Limit to docs-v2 scoped issues
+          only-labels: 'docs-v2'
+
+          # Allow up to 30 issues to be processed per run to stay within API rate limits
+          operations-per-run: 30
diff --git a/v2/es/resources/documentation-guide/automations-workflows.mdx b/v2/es/resources/documentation-guide/automations-workflows.mdx
@@ -281,6 +281,46 @@ Los flujos de trabajo de GitHub Actions se encuentran en `.github/workflows/` y
 
 ---
 
+#### Detector de incidencias obsoletas
+
+**Archivo:** `.github/workflows/stale-issue-detector.yml`
+
+**Propósito:** Marca y cierra automáticamente las incidencias de `docs-v2` que han estado inactivas durante un período prolongado.
+
+**Disparadores:**
+- Diariamente a las 03:00 UTC (programado)
+- Ejecución manual desde la interfaz de GitHub Actions
+
+**Lo que hace:**
+1. Analiza todas las incidencias abiertas de `docs-v2` en busca de inactividad
+2. Marca las incidencias con `status: stale` después de 60 días sin actividad
+3. Publica un comentario de advertencia explicando el estado obsoleto y cómo restablecerlo
+4. Cierra las incidencias obsoletas con `status: autoclosed` después de 14 días adicionales sin actividad
+5. Omite las incidencias protegidas por etiquetas de exención (ver más abajo)
+
+**Etiquetas de exención (las incidencias con alguna de estas nunca se marcan como obsoletas):**
+- `status: pinned`
+- `priority: critical` o `priority: high`
+- `classification: urgent` o `classification: high`
+- `status: in-progress`
+- `status: needs-triage`
+- `status: needs-info`
+
+**Ejecución manual:**
+1. Ir a Actions → Stale Issue Detector
+2. Hacer clic en "Run workflow"
+
+**Secretos necesarios:** Ninguno (usa `GITHUB_TOKEN`)
+
+**Notas para el mantenedor:**
+- Solo se procesan las incidencias con etiqueta `docs-v2`; las demás incidencias del repositorio no se ven afectadas
+- Eliminar la etiqueta `status: stale` de una incidencia restablece su temporizador de inactividad
+- Ajusta `days-before-issue-stale` y `days-before-issue-close` en el archivo de flujo para cambiar los umbrales
+- El límite de `operations-per-run` (30) evita superar los límites de la API de GitHub en acumulaciones grandes
+- Las solicitudes de extracción se excluyen intencionalmente (`days-before-pr-stale: -1`)
+
+---
+
 ### Flujos de obtención de datos (GitHub Actions y n8n disponibles)
 
 La implementación de GitHub Actions utiliza flujos dedicados divididos por fuente de datos (`update-forum-data.yml`, `update-ghost-blog-data.yml`, y `update-youtube-data.yml`). Las versiones de n8n de estos flujos también se mantienen para equipos que prefieren la orquestación de automatización externa.
diff --git a/v2/resources/documentation-guide/automations-workflows.mdx b/v2/resources/documentation-guide/automations-workflows.mdx
@@ -268,6 +268,46 @@ GitHub Actions workflows are located in `.github/workflows/` and run automatical
 
 ---
 
+#### Stale Issue Detector
+
+**File:** `.github/workflows/stale-issue-detector.yml`
+
+**Purpose:** Automatically marks and closes `docs-v2` issues that have been inactive for an extended period.
+
+**Triggers:**
+- Daily at 03:00 UTC (scheduled)
+- Manual dispatch from GitHub Actions UI
+
+**What it does:**
+1. Scans all open `docs-v2` issues for inactivity
+2. Marks issues with `status: stale` after 60 days of no activity
+3. Posts a warning comment explaining the stale state and how to reset it
+4. Closes stale issues with `status: autoclosed` after a further 14 days of inactivity
+5. Skips issues protected by exempt labels (see below)
+
+**Exempt labels (issues with any of these are never marked stale):**
+- `status: pinned`
+- `priority: critical` or `priority: high`
+- `classification: urgent` or `classification: high`
+- `status: in-progress`
+- `status: needs-triage`
+- `status: needs-info`
+
+**Manual execution:**
+1. Go to Actions → Stale Issue Detector
+2. Click "Run workflow"
+
+**Required secrets:** None (uses `GITHUB_TOKEN`)
+
+**Maintainer notes:**
+- Only `docs-v2`-labeled issues are processed; other repo issues are unaffected
+- Removing the `status: stale` label from an issue resets its inactivity timer
+- Adjust `days-before-issue-stale` and `days-before-issue-close` in the workflow file to change the thresholds
+- The `operations-per-run` cap (30) prevents hitting GitHub API rate limits on large backlogs
+- Pull requests are intentionally excluded (`days-before-pr-stale: -1`)
+
+---
+
 ### Data Fetching Workflows (GitHub Actions & n8n Available)
 
 The GitHub Actions implementation uses dedicated workflows split by data source (`update-forum-data.yml`, `update-ghost-blog-data.yml`, and `update-youtube-data.yml`). N8n versions of these flows are also maintained for teams that prefer external automation orchestration.
