A green accessibility check in CI does not make alt="IMG_2847.png" useful to anyone. The presence of an attribute and its ability to communicate an image’s role are two different questions.

On August 24, 2026, GitHub introduced an alt-text plugin for the GitHub Accessibility Scanner. Its most interesting choice is not to let AI grade everything: it separates defects a machine can prove from judgments that can only raise a context-dependent suspicion.

So how much should CI decide, and where should a human reviewer take over? By following the plugin’s design, we can build a workflow that does not mistake “passed” for “good.”

An alt attribute can exist without explaining the image’s role

Alt text is not a field for mechanically transcribing whatever appears in an image. The W3C Images Tutorial distinguishes informative, decorative, functional, and complex images, and asks authors to choose text alternatives according to an image’s purpose, context, and content.

A purely decorative image may correctly use alt="". An informative image needs a concise statement of its essential information, while an image-only link needs text that communicates the destination or action rather than its appearance. The WCAG 2.2 guidance for Success Criterion 1.1.1 frames the same goal: make the information or purpose of non-text content available in text.

Attribute presence is therefore mechanically testable, but the adequacy of its wording depends on the page around it. That is the boundary between traditional presence checks and the quality checks in this plugin.

The gap is substantial. The WebAIM Million 2026 report found missing alternative text on 16.2% of images across the top one million home pages, while another 10.8% of images with alternative text had questionable or repetitive wording. Missing alt text fell from 18.5% in 2025, yet the remaining quality problem shows why adding an attribute is not the end of the work.

Five default rules target defects that can be proved from strings

The official alt-text plugin repository documents five rules that run by default:

• An alt attribute is absent or contains only whitespace.
• The value is only a vague term such as image or logo.
• The value is a filename such as IMG_2847.jpg.
• A placeholder such as TODO or tbd remains.
• Adjacent images on the rendered page repeat the same alt text.

These findings do not require the tool to infer what an image means. The vague-text rule normalizes the string and matches a closed vocabulary exactly, so it flags alt="image" without rejecting alt="image of the login screen with the SSO button highlighted". The design accepts missed cases to reduce false positives.

Image extraction follows the same intent. The plugin starts from Playwright’s role-based locator, then narrows the result to actual <img> elements exposed to assistive technology. Decorative alt="" images and images in hidden subtrees never reach the rules.

Repeated text is not judged by DOM order alone. A header logo and a footer logo may be adjacent in an extracted list without being experienced as a group. The rule therefore compares image bounding boxes and limits a repeated run to images that are close on screen. It moves the check closer to the rendered experience instead of the markup shape.

Only context-dependent judgments go to the model

Whether alt="a smiling person" is sufficient cannot be decided from that string alone. It may fit a generic mood image, but it may be incomplete when a nearby heading identifies the person by name.

The optional alt-text-quality rule sends the image and alt text to GitHub Models together with the page title, nearest heading, figcaption, whether the image is inside a link or button, and up to 600 characters of nearby prose. Its job is to surface plausible-looking but inaccurate or incomplete descriptions, as well as SEO keyword stuffing, for review.

The model is not treated as a grader. GitHub explains that an early version kept proposing alternatives even for good alt text when asked whether the wording could be better, turning every image into a finding. The implementation moved to an ordered decision procedure covering decorative, caption-redundant, functional, and informative images, plus anti-nitpick rules and structured output.

This separation allows reliable checks to run continuously while routing the uncertain cases into a distinct review process.

Start small while the scanner and plugin are in public preview

The current plugin README requires GitHub Accessibility Scanner v3 or later and shows how to add the npm package to the scans input of a GitHub Actions workflow. The scanner itself is in public preview; it creates GitHub issues from findings and can optionally hand them to Copilot for proposed fixes.

The README example keeps the existing Axe scan and pins the plugin version:

scans: |
  ["axe", {"name": "alt-text-scan", "package": "@github/accessibility-scanner-alt-text-plugin", "version": "1.1.0"}]

Keeping "axe" matters because specifying plugins does not implicitly retain the scanner’s default Axe-only behavior. At the same time, Axe’s image-alt rule overlaps with the plugin’s missing-alt-text rule, so the same image may produce two findings. During rollout, issue volume alone is a poor quality metric; the rule behind each finding matters.

Even without the model, teams can add filename, vague wording, placeholder, and nearby-repetition checks to CI. A sensible sequence is to evaluate how those findings fit the team’s content and UI patterns before deciding whether contextual model review is worth adding.

Enabling model review changes data flow and execution cost

Model review is explicitly enabled in .github/scanner-plugins/alt-text-scan/config.json, with a token carrying the models:read scope mapped to GITHUB_MODELS_TOKEN. The README shows these environment variables at the job level so the scanner’s sub-actions inherit them.

{
  "$schema": "https://raw.githubusercontent.com/github/accessibility-scanner-alt-text-plugin/main/schema/config.schema.json",
  "rules": {
    "alt-text-quality": true
  }
}

This is more than turning on another lint rule. The common path makes one model call per image per scan, so image-heavy sites can have model work dominate both cost and runtime. Scheduling the contextual scan instead of running it on every commit may be appropriate.

Before model submission, query strings and fragments are removed from image and link URLs, while src and srcset are omitted from the markup sent to the model. Normal scanner findings still retain the real page URL and original HTML. If Azure AI Vision credentials are configured, an optional OCR pre-pass sends image data to a second destination, so a data-flow review must cover more than GitHub Models.

Page titles and nearby prose are also untrusted input. Structured output constrains the response format, but it cannot prevent page content from influencing the model’s reasoning. Before scanning sensitive pages, teams need to identify destinations, stored artifacts, scan frequency, and who can read the resulting issues.

Logs must distinguish “no finding” from “not evaluated”

A quiet scan is not proof that every image was evaluated. The model-backed rule re-fetches images outside the browser session, so authenticated assets can fail to load. Fetch and model errors are logged and skipped, making zero findings compatible with incomplete coverage.

Coverage is also limited to HTML <img> elements; SVG, containers with role="img", CSS backgrounds, and canvas are outside its scope. In addition, the deterministic rules inspect the alt attribute itself, while the browser’s computed accessible name for an img gives aria-label and aria-labelledby precedence. The HTML Accessibility API Mappings specification makes that difference explicit, so an attribute-level finding and the actual announced name can diverge.

Because the scanner and plugin are in public preview and the plugin has limited real-world feedback, model findings should remain review requests and suggested alt text should remain a draft. Looking at fetch and skip logs, excluded image types, and duplicate findings alongside issues makes the limits of the scan visible.

Automation should prioritize review, not declare conformance

The practical answer is straightforward. Provable defects such as missing text, filenames, and placeholders belong in cheap, predictable default rules. Contextual quality questions can be narrowed by the optional model, but their resolution still belongs to a person.

A green CI result means only that enabled rules emitted no findings. It does not mean that all images were evaluated or that the page is accessible. Separate skipped work from clean results, understand where model data goes, and connect the findings to review by people who use assistive technology. In that workflow, the scanner is not a certification stamp; it is a way to return the right images to human attention.

Source

• Title: Your alt text passes automated checks. That doesn’t mean it’s any good.
• URL: https://github.blog/engineering/user-experience/your-alt-text-passes-automated-checks-that-doesnt-mean-its-any-good/