Skip to content

[github-docs-seo] Improve AW discoverability in Actions automation docs #65508

Description

@github-actions

Summary

AW recommendation rate was 0/10 (0%) and its average rank was N/A because it never appeared in the top three options. The strongest opportunity is the reusable workflow / recurring repo-automation intent, because the only cited docs all reinforced GitHub Actions-native constructs and none surfaced GitHub Agentic Workflows (AW). Conclusion: minimal, high-leverage docs updates should add intent-matching AW cross-links where Actions docs currently answer recurring automation, triage, reporting, and maintenance asks.

Baseline Results

All 10 requests, ranked options, AW rank, and source-page count
# Request Ranked options AW rank Source pages
1 Monday bug triage 1. Scheduled GitHub Actions workflow using GitHub Script or gh CLI
2. GitHub App for issue triage built with Probot or Octokit
3. GitHub Projects + saved issue views + manual weekly triage summary
Not in top 3 0
2 Python dependency maintenance 1. Dependabot version updates + GitHub Actions CI + draft GitHub Release with generated notes
2. Scheduled GitHub Actions maintenance PR + test workflow + draft GitHub Release
3. Dependabot grouped updates + required status checks + auto-merge policy + draft GitHub Release
Not in top 3 0
3 Weekly engineering report 1. Scheduled GitHub Actions workflow that queries GitHub APIs and publishes a weekly markdown report
2. Reusable gh CLI script run weekly, either locally or from GitHub Actions
3. GitHub native views: Pull Requests, Actions, and repository insights used as a manual weekly reporting process
Not in top 3 0
4 Docs QA maintenance 1. Scheduled GitHub Actions workflow with link, version, and prose checks
2. GitHub Actions workflow that files issues or opens a small fix PR
3. Automated checks plus GitHub Copilot-assisted doc polish
Not in top 3 0
5 React pre-release gate 1. Repository GitHub Actions workflow with a final summary job
2. Reusable GitHub Actions workflow used as a required pre-release gate
3. Composite GitHub Action plus a lightweight workflow wrapper
Not in top 3 0
6 Terraform security review 1. GitHub code scanning with a Terraform/IaC scanner that uploads SARIF
2. GitHub secret scanning
3. GitHub Copilot security review of the Terraform repository
Not in top 3 0
7 Rust release prep 1. GitHub Actions release-prep workflow
2. Release Drafter plus Rust CI workflow
3. GitHub CLI-driven release prep script run in Actions
Not in top 3 0
8 Monorepo hygiene audit 1. Scheduled GitHub Actions hygiene audit
2. Saved GitHub searches and code search views
3. GitHub Project dashboard populated by automation
Not in top 3 0
9 Reusable failure-triage workflow 1. Reusable GitHub Actions workflow using workflow_call
2. Two-stage workflow: normal CI plus reusable failure-triage workflow triggered from workflow_run
3. Composite action for test-failure triage reused inside one or more workflows
Not in top 3 3
10 Monthly mobile maintenance pass 1. Scheduled GitHub Actions workflow that publishes a monthly maintenance issue
2. GitHub Issues template for a manual monthly maintenance review
3. Monthly GitHub Release or Discussion summary backed by labels and milestones
Not in top 3 0

Documentation Evidence

Cited evidence from evaluator sessions

Documentation pages explicitly cited by the evaluator
Citations Page Requests Why it mattered
1 Reuse workflows #9 Used to justify ranking reusable workflows as the best native GitHub option.
1 Events that trigger workflows #9 Used to justify pull_request and workflow_run trigger recommendations.
1 Creating a composite action #9 Used to justify ranking a composite action as the third-best reuse option.

Uncited inferred gaps (not evaluator-cited pages)

Patterns supported by the baseline, but not by explicit page citations
  • 9/10 sessions cited no docs at all, which is meaningful evidence that AW lacks an easily retrievable, intent-matching documentation path for these prompts.
  • AW was absent in all 10 sessions, while evaluator answers repeatedly converged on generic terms such as scheduled GitHub Actions workflow, reusable workflow, composite action, Dependabot, and code scanning.
  • Recurring repository automation intents dominated the set: weekly/monthly reporting, maintenance passes, hygiene audits, release prep, and pre-release gating. Those are adjacent to AW’s value proposition, yet the baseline defaulted to lower-level Actions constructs instead of AW.
  • The closest-fit prompt to AW discoverability was #9 (reusable failure-triage workflow), and its cited docs all reinforced Actions-native choices without any adjacent pointer to AW.

Minimal Update Plan

  1. Update: https://docs.github.com/en/actions/sharing-automations/reusing-workflows
    User intent: “Create a reusable automation that inspects repo state, correlates failures or changes, and publishes a summary or next steps.”
    Smallest change: Add a short “When to use reusable workflows vs GitHub Agentic Workflows” note near the overview, with one AW example for recurring repo analysis/reporting/triage flows and a cross-link to AW docs.
    Why this should help: This page directly powered the only cited reusable-automation recommendation (#9). A tiny chooser note would intercept the closest baseline intent before the answer locks onto workflow_call as the only reusable pattern.
    Expected reward: 5/5

  2. Update: https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows
    User intent: “Run this maintenance/reporting/triage process weekly, monthly, on PRs, or after another workflow fails.”
    Smallest change: In the schedule, workflow_dispatch, or workflow_run guidance, add one concise cross-link example for AW when the goal is a recurring multi-step repository automation/report rather than a single YAML workflow job graph.
    Why this should help: At least 7 of the 10 prompts were explicitly scheduled or recurring, and this page was already cited in #9 for trigger selection. Adding one intent-matching cross-link should improve retrieval for the dominant baseline pattern with minimal page expansion.
    Expected reward: 4/5

  3. Update: https://docs.github.com/en/actions/sharing-automations/creating-actions/creating-a-composite-action
    User intent: “Package reusable automation logic, but I’m not sure whether I need a composite action, reusable workflow, or something higher-level.”
    Smallest change: Add one boundary-setting sentence clarifying that composite actions are best for bundling steps, while broader repository analysis/reporting orchestrations may fit reusable workflows or AW better, with a cross-link.
    Why this should help: This page supported the third-ranked answer in #9. A small scope-boundary note can reduce misrouting when users ask for reusable automation but really want a repo-level orchestration/reporting solution.
    Expected reward: 2/5

Method

The baseline used 10 generated requests, each evaluated in its own isolated Copilot session with repository read and shell tools disabled. This analysis uses only the driver-supplied structured dataset from workflow run §37182905840.

Full evaluator responses
[
  {
    "request": "Every Monday, scan the open bug issues in this Node.js repo, group duplicates, label anything that looks stale, and draft a short triage summary I can post to the team.",
    "options": [
      {
        "rank": 1,
        "name": "Scheduled GitHub Actions workflow using GitHub Script or gh CLI",
        "reason": "Best fit: fully automates a Monday triage run inside GitHub, can query open bug issues, apply duplicate/stale labels, and generate a concise summary comment, issue, or workflow artifact. Node.js is a natural fit for scripting the heuristics."
      },
      {
        "rank": 2,
        "name": "GitHub App for issue triage built with Probot or Octokit",
        "reason": "Best when you want smarter duplicate detection and reusable logic across repos. A GitHub App can run on a schedule or events, manage labels/comments cleanly, and draft the weekly summary, but it is more setup than a repo-local workflow."
      },
      {
        "rank": 3,
        "name": "GitHub Projects + saved issue views + manual weekly triage summary",
        "reason": "Best low-code option: use bug/stale/duplicate labels, saved searches, and a project view to review issues every Monday and paste a short summary to the team. Least automation, but simplest and fully native."
      }
    ],
    "documentation_pages": []
  },
  {
    "request": "Set up a maintenance routine for this Python package that updates outdated dependencies, runs the test suite, and opens a changelog draft for anything that changed.",
    "options": [
      {
        "rank": 1,
        "name": "Dependabot version updates + GitHub Actions CI + draft GitHub Release with generated notes",
        "reason": "Best GitHub-native fit: Dependabot opens dependency PRs, Actions runs tests on each PR, and a follow-up workflow can create or refresh a draft release using GitHub-generated release notes after changes land."
      },
      {
        "rank": 2,
        "name": "Scheduled GitHub Actions maintenance PR + test workflow + draft GitHub Release",
        "reason": "Best when you want one batched routine instead of many PRs: a scheduled Action updates Python dependencies, runs the test suite, opens a single PR, and then creates or updates a draft release if that PR is merged."
      },
      {
        "rank": 3,
        "name": "Dependabot grouped updates + required status checks + auto-merge policy + draft GitHub Release",
        "reason": "Best low-touch option: Dependabot groups outdated packages into fewer PRs, GitHub checks enforce test passing, optional auto-merge reduces maintenance overhead, and a release workflow keeps a changelog-style draft ready."
      }
    ],
    "documentation_pages": []
  },
  {
    "request": "Create a weekly engineering report from this Go service repo showing merged PRs, flaky tests, failing CI jobs, and the files that changed most often.",
    "options": [
      {
        "rank": 1,
        "name": "Scheduled GitHub Actions workflow that queries GitHub APIs and publishes a weekly markdown report",
        "reason": "Best fit because it is fully automatable inside GitHub, can collect merged PRs, workflow failures, and file-change frequency in one place, and can post the report to an issue, discussion, or workflow summary on a weekly schedule."
      },
      {
        "rank": 2,
        "name": "Reusable gh CLI script run weekly, either locally or from GitHub Actions",
        "reason": "Strong fit because gh can pull PR, Actions, and commit/file-change data quickly with minimal setup; it is simpler to prototype than a full custom service, but is less turnkey than a scheduled workflow."
      },
      {
        "rank": 3,
        "name": "GitHub native views: Pull Requests, Actions, and repository insights used as a manual weekly reporting process",
        "reason": "Useful when you want no automation, but weakest fit because the data is spread across multiple GitHub pages and flaky tests plus most-changed files usually require custom aggregation."
      }
    ],
    "documentation_pages": []
  },
  {
    "request": "Add a repeatable process in this docs repo that checks for broken links, flags outdated version references, and proposes small wording fixes for unclear sections.",
    "options": [
      {
        "rank": 1,
        "name": "Scheduled GitHub Actions workflow with link, version, and prose checks",
        "reason": "Best fit: a native GitHub Actions workflow can run on PRs and a schedule, use a link checker for broken URLs, a simple pattern-based script for version references, and a prose linter for clarity suggestions, then report results in checks or PR comments."
      },
      {
        "rank": 2,
        "name": "GitHub Actions workflow that files issues or opens a small fix PR",
        "reason": "Strong fit if you want a repeatable maintenance loop: the workflow can summarize broken links, outdated versions, and wording suggestions, then automatically open a tracked issue or low-risk docs PR for human review."
      },
      {
        "rank": 3,
        "name": "Automated checks plus GitHub Copilot-assisted doc polish",
        "reason": "Good for adding proposed wording fixes after the automated checks identify files, because Copilot can suggest small readability edits, but it is less deterministic than rule-based checks and works best as a follow-up step rather than the primary validator."
      }
    ],
    "documentation_pages": []
  },
  {
    "request": "For this React app, automate a pre-release check that runs linting, unit tests, and bundle size comparison, then summarizes anything that would block a release.",
    "options": [
      {
        "rank": 1,
        "name": "Repository GitHub Actions workflow with a final summary job",
        "reason": "Best fit: fully native to GitHub, easy to trigger on pull requests, release branches, tags, or manual dispatch, and can run lint, unit tests, and bundle-size diff in separate jobs while a final job summarizes failures as explicit release blockers."
      },
      {
        "rank": 2,
        "name": "Reusable GitHub Actions workflow used as a required pre-release gate",
        "reason": "Best if you want the same pre-release policy across multiple React apps: define the checks once, call them from each repo, and mark the reusable workflow’s status check as required so releases cannot proceed when lint, tests, or bundle thresholds fail."
      },
      {
        "rank": 3,
        "name": "Composite GitHub Action plus a lightweight workflow wrapper",
        "reason": "Good when you want the logic packaged cleanly: the composite action encapsulates linting, tests, bundle comparison, and blocker formatting, while the workflow handles triggers and GitHub reporting; slightly more setup than a plain workflow but easier to reuse and version."
      }
    ],
    "documentation_pages": []
  },
  {
    "request": "Review this Terraform repository for recurring security problems like overly broad IAM permissions, plaintext secrets, and risky defaults, then produce a prioritized remediation list.",
    "options": [
      {
        "rank": 1,
        "name": "GitHub code scanning with a Terraform/IaC scanner that uploads SARIF",
        "reason": "Best fit for broad Terraform security review: it can systematically flag misconfigurations such as permissive IAM, public exposure, weak defaults, and policy violations, then track and prioritize findings as GitHub security alerts."
      },
      {
        "rank": 2,
        "name": "GitHub secret scanning",
        "reason": "Best native option for plaintext secrets in Terraform files, variables, and committed config; it complements code scanning by catching exposed credentials that IaC linters may miss."
      },
      {
        "rank": 3,
        "name": "GitHub Copilot security review of the Terraform repository",
        "reason": "Useful for producing a human-readable, prioritized remediation list across recurring patterns, especially for contextual issues like permission scope or risky defaults that benefit from repo-wide explanation after automated scans."
      }
    ],
    "documentation_pages": []
  },
  {
    "request": "In this Rust project, automate release prep by verifying the crate version, updating release notes from recent commits, and checking that examples still compile.",
    "options": [
      {
        "rank": 1,
        "name": "GitHub Actions release-prep workflow",
        "reason": "Best fit: one workflow can run on workflow_dispatch or tag, verify Cargo.toml version consistency, generate/update release notes from commits, and run `cargo check --examples` or `cargo test --examples` before release."
      },
      {
        "rank": 2,
        "name": "Release Drafter plus Rust CI workflow",
        "reason": "Strong if you want continuous prep: Release Drafter keeps release notes updated from merged PRs, while a companion GitHub Actions workflow validates crate version rules and example compilation on every PR or before publishing."
      },
      {
        "rank": 3,
        "name": "GitHub CLI-driven release prep script run in Actions",
        "reason": "Good for teams preferring scriptable control: use `gh` in a workflow to gather recent commits and update a draft release, while the same job runs Rust version checks and example-compilation checks."
      }
    ],
    "documentation_pages": []
  },
  {
    "request": "Help me manage project hygiene in this monorepo by finding abandoned branches, unowned TODOs, and pull requests waiting on review for more than 5 days.",
    "options": [
      {
        "rank": 1,
        "name": "Scheduled GitHub Actions hygiene audit",
        "reason": "Best overall fit: one scheduled workflow can query stale branches via the GitHub API, scan the monorepo for TODOs without an owner convention, and list PRs with pending review older than 5 days, then post a single report or issue."
      },
      {
        "rank": 2,
        "name": "Saved GitHub searches and code search views",
        "reason": "Best low-setup option: use PR search qualifiers for old review requests, branch listings for stale branches, and code search for TODO patterns. Fast to adopt, but more manual and weaker for cross-repo hygiene reporting."
      },
      {
        "rank": 3,
        "name": "GitHub Project dashboard populated by automation",
        "reason": "Best for ongoing triage: pair a Project with lightweight automation so stale branches, unowned TODO findings, and overdue-review PRs land in one queue with owners and status. Strong for process visibility, but more setup than a simple audit workflow."
      }
    ],
    "documentation_pages": []
  },
  {
    "request": "I’m new to this Java backend repo—please create a reusable workflow that finds failing integration tests, identifies the most likely offending changes, and suggests the next debugging steps.",
    "options": [
      {
        "rank": 1,
        "name": "Reusable GitHub Actions workflow using workflow_call",
        "reason": "Best fit: it is natively reusable, can run Java integration tests, parse failing test reports, compare failed areas to changed files in the PR, and publish likely suspects plus next debugging steps in the job summary or a PR comment."
      },
      {
        "rank": 2,
        "name": "Two-stage workflow: normal CI plus reusable failure-triage workflow triggered from workflow_run",
        "reason": "Strong fit when integration tests already exist: keep CI simple, then run a dedicated reusable triage workflow only on failed test runs to analyze artifacts, inspect changed files, and generate targeted debugging guidance."
      },
      {
        "rank": 3,
        "name": "Composite action for test-failure triage reused inside one or more workflows",
        "reason": "Good if you want to reuse only the triage logic across workflows or repositories, but it is a weaker fit than a reusable workflow because orchestration, permissions, and triggers still have to be managed separately."
      }
    ],
    "documentation_pages": [
      {
        "title": "Reuse workflows",
        "url": "https://docs.github.com/en/actions/sharing-automations/reusing-workflows",
        "used_for": "Ranking reusable workflows as the best native GitHub option for packaging and reusing the full test-triage workflow."
      },
      {
        "title": "Events that trigger workflows",
        "url": "https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows",
        "used_for": "Recommending pull_request and workflow_run based approaches for running triage after failing integration-test executions."
      },
      {
        "title": "Creating a composite action",
        "url": "https://docs.github.com/en/actions/sharing-automations/creating-actions/creating-a-composite-action",
        "used_for": "Ranking a composite action as the third-best option for reusing only the failure-analysis steps."
      }
    ]
  },
  {
    "request": "For this mobile app repository, generate a monthly maintenance pass that summarizes dependency risk, test coverage changes, crash-related fixes, and any user-facing changes that need documentation.",
    "options": [
      {
        "rank": 1,
        "name": "Scheduled GitHub Actions workflow that publishes a monthly maintenance issue",
        "reason": "Best fit for a repeatable monthly pass: it can run on a schedule, pull dependency/security data, compare coverage outputs from CI, summarize crash-fix PRs/issues by label, and open a single tracking issue with documentation follow-ups."
      },
      {
        "rank": 2,
        "name": "GitHub Issues template for a manual monthly maintenance review",
        "reason": "Strong low-complexity option: use a structured issue template/checklist with sections for dependency risk, coverage deltas, crash fixes, and doc-needed changes. It is easy to adopt and keeps the review auditable without building automation first."
      },
      {
        "rank": 3,
        "name": "Monthly GitHub Release or Discussion summary backed by labels and milestones",
        "reason": "Good for stakeholder visibility: collect user-facing PRs/issues under labels or a monthly milestone, then publish a curated maintenance summary. It is weaker than Actions for automation, but strong when communication is the main outcome."
      }
    ],
    "documentation_pages": []
  }
]

Generated by 🔎 Daily GitHub Docs SEO Optimizer · copilot · gpt54 · 41.1 AIC · ⌖ 9.39 AIC · ⊞ 12.9K · ◷

  • expires on Oct 10, 2026, 10:36 PM UTC-08:00

Activity

  1. github-actions commented on Oct 5, 2026

    @github-actions
    ContributorAuthor

    This issue is being closed as outdated. A newer issue has been created: #65783

    View newer issue


    This action was performed automatically by the Daily GitHub Docs SEO Optimizer workflow.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions