Add issue-triage agentic workflow

README.md

@@ -28,6 +28,7 @@ AI-powered [GitHub Agent Workflows](https://github.github.com/gh-aw/) for docume
 | Workflow | Description | Trigger | Safe Output |
 |----------|-------------|---------|-------------|
 | [docs-check](agentic-workflows/docs-check/) | Analyze a PR or commit for documentation impact | `/docs-check`, label, dispatch | `add-comment` |
+| [issue-triage](agentic-workflows/issue-triage/) | Triage issues by applying team labels | `/triage`, dispatch | `add-labels` |
 
 Quick install:
 

agentic-workflows/README.md

@@ -5,6 +5,7 @@ AI-powered workflows for Elastic documentation tasks. Each directory contains a
 | Workflow | Description | Trigger | Safe Output |
 |----------|-------------|---------|-------------|
 | [docs-check](docs-check/) | Analyze a PR or commit for documentation impact | `/docs-check`, label, dispatch | `add-comment` |
+| [issue-triage](issue-triage/) | Triage issues by applying team labels | `/triage`, dispatch | `add-labels` |
 
 ## Installation
 

agentic-workflows/fragments/formatting.md

@@ -0,0 +1,7 @@
+## Formatting Guidelines
+
+- Lead with the most important information — your first sentence should be the key takeaway
+- Be concise and actionable — no filler or praise
+- Use `<details>` and `<summary>` tags for long sections to keep responses scannable
+- Wrap branch names and @-references in backticks to avoid pinging users
+- Include code snippets with file paths and line numbers when referencing the codebase

agentic-workflows/fragments/mcp-pagination.md

@@ -0,0 +1,32 @@
+## MCP Pagination
+
+MCP tool responses have a **25,000 token limit**. When responses exceed this limit, the call fails and you must retry with pagination — wasting turns and tokens. Use proactive pagination to stay under the limit.
+
+### Recommended `perPage` Values
+
+- **5-10**: For detailed items (PR diffs, files with patches, issues with comments)
+- **20-30**: For medium-detail lists (commits, review comments, issue lists)
+- **50-100**: For simple list operations (branches, labels, tags)
+
+### Pagination Pattern
+
+When you need all results from a paginated API:
+
+1. Fetch the first page with a conservative `perPage` value
+2. Process the results before fetching the next page
+3. Continue fetching pages until you receive fewer results than `perPage` (indicating the last page)
+
+### Error Recovery
+
+If you see an error like:
+- `MCP tool response exceeds maximum allowed tokens (25000)`
+- `Response too large for tool [tool_name]`
+
+Retry the same call with a smaller `perPage` value (halve it).
+
+### Tips
+
+- **Start small**: It's better to make multiple small requests than one that fails
+- **Fetch incrementally**: Get an overview first, then details for specific items
+- **Use filters**: Combine `perPage` with state, label, or date filters to reduce result size
+- **Process as you go**: Don't accumulate all pages before acting — process each batch immediately

agentic-workflows/fragments/rigor.md

@@ -0,0 +1,10 @@
+## Rigor
+
+**Silence is better than noise. A false positive wastes a human's time and erodes trust in every future report.**
+
+- If you claim something is missing or broken, show the exact evidence in the code — file path, line number, and what you observed.
+- If a conclusion depends on assumptions you haven't confirmed, do not assert it. Verify first; if you cannot verify, do not report.
+- "I don't know" is better than a wrong answer. `noop` is better than a speculative finding.
+- It's worth the time to verify now versus guessing and forcing someone else to verify later.
+- Before filing any issue or opening any PR, re-read your own output as a skeptical reviewer. Ask: "Would a senior engineer on this team find this useful, or would they close it immediately?" If the answer is "close," call `noop` instead.
+- Only report findings you would confidently defend in a code review. If you feel the need to hedge with "might," "could," or "possibly," the finding is not ready to file.

agentic-workflows/fragments/runtime-setup.md

@@ -0,0 +1,53 @@
+---
+steps:
+  - name: Setup Go
+    if: hashFiles('go.mod') != ''
+    uses: actions/setup-go@v5
+    with:
+      go-version-file: go.mod
+      cache: true
+
+  - name: Setup Python
+    if: hashFiles('.python-version') != ''
+    uses: actions/setup-python@v5
+    with:
+      python-version-file: '.python-version'
+
+  - name: Setup Node.js (.node-version)
+    if: hashFiles('.node-version') != ''
+    uses: actions/setup-node@v6
+    with:
+      node-version-file: '.node-version'
+
+  - name: Setup Node.js (.nvmrc)
+    if: hashFiles('.node-version') == '' && hashFiles('.nvmrc') != ''
+    uses: actions/setup-node@v6
+    with:
+      node-version-file: '.nvmrc'
+
+  - name: Setup Ruby
+    if: hashFiles('.ruby-version') != ''
+    uses: ruby/setup-ruby@v1
+    with:
+      ruby-version: '.ruby-version'
+      bundler-cache: true
+
+  - name: Setup uv
+    if: hashFiles('pyproject.toml', 'uv.lock') != ''
+    uses: astral-sh/setup-uv@v5
+    id: setup-uv
+
+  - name: Expose uv in workspace
+    if: hashFiles('pyproject.toml', 'uv.lock') != ''
+    shell: bash
+    env:
+      UV_PATH: ${{ steps.setup-uv.outputs.uv-path }}
+      WORKSPACE: ${{ github.workspace }}
+    run: |
+      set -euo pipefail
+      install_dir="$WORKSPACE/.gh-aw-tools/bin"
+      mkdir -p "$install_dir"
+      cp "$UV_PATH" "$install_dir/uv"
+      chmod +x "$install_dir/uv"
+      echo "$install_dir" >> "$GITHUB_PATH"
+---

agentic-workflows/fragments/scheduled-report.md

@@ -0,0 +1,67 @@
+# Scheduled Report Agent
+
+You are a report agent for ${{ github.repository }}. You run on a schedule to investigate the repository and file an issue when something needs attention. Your specific assignment is described in the **Report Assignment** section below.
+
+## Context
+
+- **Repository**: ${{ github.repository }}
+
+## Constraints
+
+This workflow is for detection and reporting only. You can read files, search code, run commands, and read PR/issue details — but your only output is either a single issue or a noop.
+
+## Process
+
+Follow these steps in order.
+
+### Step 1: Gather Context
+
+1. Call `generate_agents_md` to get the repository's coding guidelines and conventions. If this fails, continue without it.
+2. Follow the data gathering instructions in the **Report Assignment** section.
+
+### Step 2: Analyze
+
+Follow the analysis instructions in the **Report Assignment** section to determine whether an issue should be filed. The Report Assignment defines:
+- What data to gather and how
+- What to look for
+- What constitutes a finding worth reporting
+- What to skip or ignore
+
+### Step 3: Self-Review (Quality Gate)
+
+Before filing anything, critically evaluate every finding against these criteria:
+
+1. **Evidence is concrete** — you can point to exact file paths, line numbers, commit SHAs, or command outputs. No "I believe" or "it seems."
+2. **Finding is actionable** — a maintainer reading the issue can act on it without re-investigating from scratch.
+3. **Finding is not already tracked** — you checked open issues and recent PRs for duplicates.
+4. **Finding is worth a human's time** — the issue is material enough that a maintainer would thank you for filing it, not close it as noise.
+
+If zero findings pass all four criteria, call `noop` with a brief reason and stop. **Noop is the expected outcome most days.** Filing nothing is a success when there is nothing worth filing.
+
+### Step 4: Report
+
+If there are findings that pass the quality gate, call `create_issue` with a structured report. Use the issue format specified in the Report Assignment if one is provided, otherwise use this default format:
+
+**Issue title:** Brief summary of findings
+
+**Issue body:**
+
+> ## Findings
+>
+> ### 1. [Brief description]
+>
+> **Evidence:** [Links, references, or data supporting the finding]
+> **Action needed:** [What should be done]
+>
+> ## Suggested Actions
+>
+> - [ ] [Actionable checkbox for each finding]
+
+**Guidelines:**
+- Group related findings together
+- Be specific about what needs to happen
+- Include links and references where possible
+- Make suggested actions concrete enough to act on without re-investigating
+- If a finding is ambiguous, it does not pass the quality gate — drop it
+
+## Report Assignment

agentic-workflows/issue-triage/README.md

@@ -0,0 +1,48 @@
+# Issue Triage
+
+Triages issues by analyzing content and applying the appropriate team label. Uses the Elastic Docs MCP server and CODEOWNERS to determine ownership.
+
+## Triggers
+
+| Event | Description |
+|-------|-------------|
+| `/triage` | Slash command on an issue comment |
+| `workflow_dispatch` | Manual trigger (batch mode: triages all `needs-team` issues) |
+
+## Install
+
+```bash
+mkdir -p .github/workflows && curl -sL \
+  https://raw.githubusercontent.com/elastic/docs-actions/v1/agentic-workflows/issue-triage/example.yml \
+  -o .github/workflows/issue-triage.yml
+```
+
+Ensure the `COPILOT_GITHUB_TOKEN` secret is configured in your repository.
+
+## Inputs
+
+| Input | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `additional-instructions` | string | No | `""` | Team mapping, label rules, CODEOWNERS paths |
+| `setup-commands` | string | No | `""` | Shell commands to run before the agent starts |
+| `messages-footer` | string | No | _(default footer)_ | Footer appended to all agent comments |
+
+## Safe Outputs
+
+| Output | Max | Description |
+|--------|-----|-------------|
+| `noop` | — | No issues to triage or no labels needed |
+| `add-labels` | 30 | Apply team labels to issues |
+
+Allowed labels: `Team:Admin`, `Team:Developer`, `Team:DocsEng`, `Team:Experience`, `Team:Ingest`, `Team:Projects`, `cross-team`.
+
+## How it works
+
+1. Pre-steps fetch issue data and CODEOWNERS to `/tmp/gh-aw/triage-data/`
+2. The agent reads each issue, uses the Elastic Docs MCP server to gather context about referenced pages
+3. For docs stored outside the current repo, it fetches the relevant repo's CODEOWNERS via `gh api`
+4. It applies the best-fit team label via `add_labels`
+
+## Example
+
+The `example.yml` includes the full docs-content team mapping via `additional-instructions`. Customize the mapping for your repo's team structure.

agentic-workflows/issue-triage/example.yml

@@ -0,0 +1,33 @@
+name: Issue Triage
+on:
+  issue_comment:
+    types: [created]
+  issues:
+    types: [opened, labeled]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  issues: read
+
+jobs:
+  run:
+    uses: elastic/docs-actions/.github/workflows/gh-aw-issue-triage.lock.yml@v1
+    with:
+      additional-instructions: |
+        ## Team Ownership Mapping
+
+        | Team Label | Owns | Keywords / URL paths |
+        |---|---|---|
+        | `Team:Admin` | Elasticsearch admin, cluster mgmt, cloud, deployment docs | Cluster management, index management, security (auth, roles, API keys), snapshots, ILM, data lifecycle, CCR, CCS, licensing, upgrade, monitoring, Elastic Cloud, ECE, ECK, serverless. Paths: `deploy-manage/`, `cloud-account/`, `manage-data/` (except `manage-data/ingest/`), `serverless/`, `troubleshoot/deployments/`, `troubleshoot/elasticsearch/` |
+        | `Team:Experience` | Kibana, observability solution, security solution | Kibana, dashboards, visualizations, Discover, observability, APM UI, maps, canvas, Lens, alerting, rules, cases, SIEM, endpoint security, detection rules, security analytics. Paths: `explore-analyze/` (default), `solutions/observability/`, `solutions/security/`, `reference/kibana/`, `reference/observability/`, `reference/security/` |
+        | `Team:Developer` | Elasticsearch developer, search solution docs | Elasticsearch APIs, ES|QL, query DSL, search features, relevance, vector search, semantic search, inference APIs, connectors, developer tools, clients, search applications, App Search, Workplace Search. Paths: `solutions/search/`, `reference/elasticsearch/clients/`, `reference/search/`, `reference/machine-learning/`, `explore-analyze/ai-features/`, `explore-analyze/cross-cluster-search/`, `explore-analyze/cross-project-search/`, `explore-analyze/transforms/` |
+        | `Team:Ingest` | Data ingestion, Fleet, APM agents docs | Fleet, Elastic Agent, Beats, Logstash, pipelines, integrations, data streams, APM agents, APM server, OpenTelemetry. Paths: `manage-data/ingest/`, `reference/apm-agents/`, `reference/fleet/`, `reference/ingestion-tools/`, `solutions/observability/apm/apm-agents/`, `solutions/observability/apm/apm-server/`, `solutions/observability/apm/ingest/`, `solutions/observability/apm/opentelemetry/` |
+        | `Team:DocsEng` | Docs infrastructure | Docs build system, CI/CD, website rendering, broken navigation, docs-builder bugs, elastic.co website issues not related to content. Paths: `.github/workflows/`, `.github/scripts/` |
+        | `Team:Projects` | Internal projects, docs initiatives, fallback | Internal documentation projects, content strategy, information architecture, get-started guides, or when no other team fits. Paths: `get-started/` |
+
+        **Shared ownership**: Some paths have shared ownership (e.g., `/explore-analyze/machine-learning/` is shared by Developer and Experience). Pick the team whose keywords best match the issue content.
+        **Internal projects**: If the issue seems related to an internal documentation project, initiative, or content strategy effort, apply `Team:Projects`.
+        **Fallback**: Use `Team:Projects` if you genuinely cannot determine the owning team.
+    secrets:
+      COPILOT_GITHUB_TOKEN: ${{ secrets.COPILOT_GITHUB_TOKEN }}