Add a living pixel-art koi to your GitHub profile README (in 5 minutes)

Your GitHub profile README can do more than list tech badges. With git-koi you get a small pixel-art koi that is redrawn every night from your public activity: languages color it, contributions make it grow, and streaks mark it.

I added it to my own profile today, and it took a few minutes. Here is exactly how, plus the three things that surprised me.

Credit: git-koi is an open source project (MIT license) by yalongwastaken. I'm only showing how to set it up.

What you need

• A profile repository: a public repo named exactly like your username (for example PushoDev/PushoDev). Its README.md is what GitHub shows on your profile.
• Nothing else. The Action uses the built-in GITHUB_TOKEN, so there are no secrets to create, and you don't need Rust or the GitHub CLI.

Step 1: add the workflow

Create the file .github/workflows/koi.yml in your profile repo:

name: Koi
on:
  schedule:
    # Just after midnight UTC, so the koi shows the day that just ended.
    - cron: "20 0 * * *"
  workflow_dispatch:
  push:
    paths: [.github/workflows/koi.yml]
permissions:
  contents: write
concurrency: koi
jobs:
  koi:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: yalongwastaken/git-koi@v1
        with:
          body: white
          output-dir: koi
      - name: Commit the koi if it changed
        shell: bash
        run: |
          git add koi/koi.gif
          if git diff --cached --quiet; then
            echo "The koi is unchanged; nothing to commit."
            exit 0
          fi
          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git commit --quiet --message "koi: draw the day's koi"
          git push --quiet

What it does:

• Runs every night at 00:20 UTC, so each koi shows the day that just ended.
• Also runs when you push a change to this file, so you don't have to wait until midnight for the first one.
• permissions: contents: write lets the job commit the generated GIF back to your repo.
• The Action itself never commits; the last step does it, and only if the image changed.

Step 2: show it in your README

Add this where you want the koi to appear:

<p align="center">
  <img src="koi/koi.gif" width="256" alt="My GitHub koi" />
</p>

The GIF is drawn at twice the koi's pixel size, so width="256" shows it at its native size.

Step 3: push and check

git add .
git commit -m "Add koi"
git push origin main

Open the Actions tab, and you should see the Koi workflow running. In my case it finished in about 30 seconds and created koi/koi.gif in the repo.

If the workflow didn't start, run it by hand: Actions → Koi → Run workflow.

Make it yours

The Action has a few inputs:

To change the koi, edit body: white in your workflow and push. If you change output-dir, also update the path in the commit step and the image in your README.

The three gotchas I hit

1. The image looks broken for a minute. Right after my first push, the README showed a broken image. The workflow was still running, so koi/koi.gif didn't exist yet, and GitHub cached the "missing" result. Wait for the workflow to finish and hard-refresh (Ctrl+Shift+R).

2. Your local repo falls behind every night. The bot commits the new GIF to your repo daily, so your local copy is always one commit behind. Before your next push:

   git pull --rebase origin main
   

   Otherwise git push will be rejected.

3. Scheduled workflows pause after 60 days. GitHub disables scheduled workflows in public repos with no activity for 60 days. If your koi stops changing, re-enable it from the Actions tab or run gh workflow enable koi.yml.

One note about trust

This workflow runs a third-party Action with write access to your profile repo. It only uses the built-in token and the project is MIT-licensed, but it's a good habit to read the Action's code once, and if you want extra safety, pin it to a commit SHA instead of @v1.

Wrap-up

That's it: a small, living detail that makes your profile feel a bit more alive, with no secrets and almost no setup. If you try it, tell me how your koi looks! You can see mine at the bottom of my profile: PushoDev