README contributors — a circular wall for any GitHub repo

What

A GitHub Action that fills a README with the people the GitHub contributors API lists (plus merged-PR authors when that list is behind). Each person is a polaroid: face, name, a bit of tilt. Each card is its own link. Bots are omitted. exclude drops named logins. Merged PR Co-authored-by trailers join the wall (GitHub noreply addresses only, up to five per pull request). An empty list writes “Be the first to appear here.” Hover a cut name for the full one. caption: auto asks a model for one sentence that names this repository or the people on the wall. Stock filler is dropped. No table. No third-party list service.

Why

GitHub cannot click a face inside one SVG. One picture is one link. A wall.svg with six heads looks clickable. It is not. This Action writes one card per person. Tap it, you land on their GitHub.

Video

Same wall as the live cards above. 18 seconds. No voiceover.

Watch the AI demo

This is the model path. Zero-config leaves the wall with no caption.

The wall is still the people the contributors API lists. One polaroid per person. The model adds one italic sentence that names this repository or those people.

What. The wall is still the people the contributors API lists. The model writes one italic line that names this repository or those people.

Why. A headcount is not a story. A caption that says who showed up is.

How. caption: auto and gpt-4o-mini. Same people next week? The line is reused. No extra credits.

Live polaroid wall and model caption on the readme-contributors README — Live on the Action README. *The contributors to the py-harness project include Yauhen Bichel, Mark Xian, Itzsaurav, svkzn, Aditya, and Huangshuo Kuang.*

Cases

The Action already handles these. The videos above are two of them.

Empty wall. “Be the first to appear here.”

README polaroids. One clickable card per person. That is the wall GitHub can tap.

Pages SVG. layout and theme change the combined SVG only. Not the README cards.

12+ / 50+. Faces shrink. A name list is added from 12 people.

exclude. Named logins dropped after bots.

No caption. Zero-config. The wall is still written.

caption: auto. One italic sentence. Same people next week? The line is reused.

format: html. Polaroids only. Skips .github/contributors.svg.

Protected main. Still no pull request. Add a write deploy key as CONTRIBUTORS_DEPLOY_KEY and let deploy keys bypass the ruleset. Copy examples/contributors.yml.

Orphan faces. When a login leaves the wall, .github/faces/{login}.svg is deleted.

overlap. Facepile step. Default 0.64. 1 sits faces side by side. Pages SVG only.

Used by

Public repositories that pin this Action on their default branch.

py-harness Everyday laptop harness. This live demo is its wall. merge-cheer Merge-celebration Action. readme-contributors This Action, dogfooded on its own README. molecare-mcp Different six people. Open source. Not a medical device. molecare-skin-llm Three polaroids on the README. molecare-ml Solo wall from the same Action.

Search every public workflow that pins YauhenBichel/readme-contributors@. Also live: molecare-desktop.

How to use it

01 Add a pair of markers to README.md.
02 Call the Action. Pin the release tag, or a commit SHA if the job can write.
03 Commit the rewritten README, .github/faces, and .github/contributors.svg when you keep the SVG wall.

Markers:

<!-- readme: contributors,bots/- -start -->
<!-- readme: contributors,bots/- -end -->

Minimal workflow:

name: Contributors
on:
  schedule: [{ cron: "17 4 * * 0" }]
  workflow_dispatch:
permissions:
  contents: write
jobs:
  readme:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: YauhenBichel/readme-contributors@v1.7.0
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          # exclude: ghost
          # caption: auto
      - run: |
          git config user.name github-actions[bot]
          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
          git add README.md .github/contributors.svg .github/faces
          git diff --cached --quiet && exit 0
          git commit -m "docs: refresh README contributors"
          git push

The snippet above pushes, for an unprotected default branch. A protected default branch pushes too, through a write deploy key stored as CONTRIBUTORS_DEPLOY_KEY — copy examples/contributors.yml. Set exclude to omit logins. An empty wall writes “Be the first to appear here.” caption: auto writes one sentence that names the repository or the people on the wall.

Use a model on your repo

The wall stays rule-based. The model only writes the italic line under the faces. Live on this README now:

The contributors to the py-harness project include Yauhen Bichel, Mark Xian, Itzsaurav, svkzn, Aditya, and Huangshuo Kuang.

Yauhen Bichel and HeaTTap have contributed to the readme-contributors project.

Add the README markers from How to use it.
Settings → Secrets and variables → Actions → New repository secret named OPENAI_API_KEY.
Copy examples/contributors-openai.yml.
Run the workflow. The log prints caption: … when a line is kept.

- uses: YauhenBichel/readme-contributors@e4468b5b0cc0f8b87f0b083bc13efc9289ff7ecd
  with:
    token: ${{ secrets.GITHUB_TOKEN }}
    caption: auto
    model: gpt-4o-mini
    model-api-key: ${{ secrets.OPENAI_API_KEY }}

Pin that SHA until the next release. @v1.7.0 can call a model but only sees a headcount, so it writes filler. Stock “dedicated individuals” lines are dropped. A missing key or a 429 leaves the wall with no caption — it is not retried.

Keep credits low

A caption that still names this repository or a listed person is reused when the people list is unchanged. Same people plus a missing or stock line gets one call. Use gpt-4o-mini. One secret, one caption: auto step, weekly cron only. Do not run caption: auto on push to README.md.

Layouts

Set layout. The default stays the overlapping facepile. overlap changes the facepile step (default 0.64; 1 sits faces side by side). These drawings are Pages art. The README wall is always the clickable polaroids.

stickers

Tilted cards, chunky rings, a little lift.

- uses: YauhenBichel/readme-contributors@v1.7.0
  with:
    token: ${{ secrets.GITHUB_TOKEN }}
    layout: stickers

facepile

Overlapping circles. First person sits on top.

- uses: YauhenBichel/readme-contributors@v1.7.0
  with:
    token: ${{ secrets.GITHUB_TOKEN }}
    layout: facepile

grid

Spaced circles. Wraps at columns.

- uses: YauhenBichel/readme-contributors@v1.7.0
  with:
    token: ${{ secrets.GITHUB_TOKEN }}
    layout: grid

tiles

Rounded squares instead of circles.

- uses: YauhenBichel/readme-contributors@v1.7.0
  with:
    token: ${{ secrets.GITHUB_TOKEN }}
    layout: tiles

list

Avatar, name, and login on each row.

- uses: YauhenBichel/readme-contributors@v1.7.0
  with:
    token: ${{ secrets.GITHUB_TOKEN }}
    layout: list

compact

A tighter grid when the list is long.

- uses: YauhenBichel/readme-contributors@v1.7.0
  with:
    token: ${{ secrets.GITHUB_TOKEN }}
    layout: compact

wave

A sine-staggered row. Good for a short team.

- uses: YauhenBichel/readme-contributors@v1.7.0
  with:
    token: ${{ secrets.GITHUB_TOKEN }}
    layout: wave

orbit

The first contributor in the middle, the rest on a ring.

- uses: YauhenBichel/readme-contributors@v1.7.0
  with:
    token: ${{ secrets.GITHUB_TOKEN }}
    layout: orbit

honeycomb

Hex tiles on offset rows.

- uses: YauhenBichel/readme-contributors@v1.7.0
  with:
    token: ${{ secrets.GITHUB_TOKEN }}
    layout: honeycomb

ribbon

A zipper row that steps up and down.

- uses: YauhenBichel/readme-contributors@v1.7.0
  with:
    token: ${{ secrets.GITHUB_TOKEN }}
    layout: ribbon

constellation

Faces with faint links between neighbours.

- uses: YauhenBichel/readme-contributors@v1.7.0
  with:
    token: ${{ secrets.GITHUB_TOKEN }}
    layout: constellation

banner

The first person is larger; the others sit beside them.

- uses: YauhenBichel/readme-contributors@v1.7.0
  with:
    token: ${{ secrets.GITHUB_TOKEN }}
    layout: banner

Themes

Set theme. auto follows the reader’s light or dark README. The others paint a frame.

midnight

- uses: YauhenBichel/readme-contributors@v1.7.0
  with:
    token: ${{ secrets.GITHUB_TOKEN }}
    layout: facepile
    theme: midnight

sunrise

theme: sunrise

forest

theme: forest

ocean

theme: ocean

mono

theme: mono

theme also accepts auto and github.