A GitHub bot that nags about image alt text so humans don’t have to

GitHub has open sourced accessibility-alt-text-bot, a GitHub Action that automatically reminds users when they share images without meaningful alt text in Issues, Discussions, and Pull Requests. The bot posts a comment on any contribution that includes an image lacking an accessible textual description.

Alt text—short for alternative text—is the code attached to an image that conveys its intent to people using screen readers or other assistive technologies. This includes users who are blind, have low vision, or have cognitive disabilities. Without it, images shared in a repository create an accessibility barrier that excludes people from the conversation. W3C’s Images Tutorial provides further guidance on writing effective alt text.

A common example: a contributor includes an “After” screenshot in a pull request description to show UI changes. If that image has no textual description, reviewers who rely on assistive technology cannot understand what changed.

Why automate the reminder?

Most GitHub users simply don’t know what alt text is or why it matters—and GitHub’s interface doesn’t prompt them to add it. The result is a cycle of manual reminders: screen reader users constantly ask colleagues to add alt text, and accessibility advocates find themselves sending the same messages over and over. That back-and-forth delays collaboration and contributes to what Shell Little’s Axe-Con talk describes as advocacy fatigue—burnout from constantly defending and advocating for accessibility.

The accessibility-alt-text-bot was built to lift that burden off individuals and replace it with a system that advocates at scale, while the GitHub team continues working toward baking accessibility features directly into the platform.

Setup

Installing the action requires adding the following workflow to a .yml file inside the .github/workflows directory of your repository:

name: Accessibility-alt-text-bot
on: 
  issues:
    types: [opened, edited]
  pull_request:
    types: [opened, edited]
  issue_comment:
    types: [created, edited]
  discussion:
    types: [created, edited]
  discussion_comment:
    types: [created, edited]

permissions:
  issues: write
  pull-requests: write
  discussions: write

jobs:
  accessibility_alt_text_bot:
    name: Check alt text is set on issue or pull requests
    runs-on: ubuntu-latest
    if: ${{ github.event.issue || github.event.pull_request || github.event.discussion }}
    steps:
      - name: Get action 'github/accessibility-alt-text-bot'
        uses: github/[email protected] # Set to latest

Once installed, the bot monitors activity in your repository. When a pull request contains an image determined to have insufficient alt text, it automatically leaves a comment prompting the user to add the missing description.

Screenshot of an automated actions comment on a GitHub Issue that says, 
“Uh oh! @monalisa, the image you shared is missing helpful alt text. Check your issue body. Alt text is an invisible description that helps screen readers describe images to blind or low-vision users. If you are using markdown to display images, add your alt text inside the brackets of the markdown image”, followed by a link to learn more about setting alt text on GitHub Docs.

Adoption in your projects creates a more inclusive open source environment. Questions and feedback can be filed in the github/accessibility-alt-text-bot repository. More on GitHub’s broader accessibility efforts is available at accessibility.github.com.