GreenWall: drawing pixel art on the GitHub contribution graph

What GreenWall solves, and for whom

The GitHub contribution graph is a fixed grid. It has 7 rows for the days of the week and up to 52 columns for the weeks of a year, and each cell is shaded by how many contributions landed on that date. GreenWall treats that grid as a canvas. The README describes the workflow as uploading an image (PNG, JPG or SVG), choosing rows between 1 and 7 and columns between 1 and 52 to match the image's shape, and then placing the resulting pattern on the calendar.

The audience is narrow and specific. This is for someone who wants a recognizable shape, a logo, a piece of text, or a photo to show up on their own profile, and who is comfortable with the fact that the result is produced by generating commits rather than by doing work. The README's disclaimer frames the project as being for educational, demonstration and research purposes related to GitHub contribution mechanics, and puts misuse on the user. That framing matters: the tool does not pretend the commits are anything other than a rendering medium.

The image-to-heatmap pipeline and its two modes

The core mechanism is image processing followed by commit generation. An uploaded image is scaled down to the row and column count you choose, and each resulting cell is reduced to a shade. GreenWall then maps those shades onto commit counts so that darker cells get more commits and lighter cells get fewer or none.

Two modes cover most inputs. Auto is described as working for most photos and grayscale images. Binary is described as best for black-on-white text or line art. The controls around them are the part that determines whether the output is legible: brightness invert, threshold, scaling filter, and what the README calls stroke recovery and stroke dilation. The scaling filter matters more than it sounds. For sharp text the README says to keep it on Nearest to preserve sharp edges, because any smoothing filter will blur a one-pixel stroke into a gray cell that no longer reads as part of a letter.

The README's own quick guide is a useful admission of how fiddly this gets. Black text on white wants Binary with invert on, Nearest smoothing, threshold 0 to 10, recovery 1 at 12 to 24, and dilation 0 to 1. Very thin lines of 2px or less want recovery 1 pushed to 20 to 28 and dilation 1 to 2. Those are not default settings that happen to work; they are corrections for specific failure modes, which tells you the automatic path does not always produce a clean result.

Installing GreenWall and pushing a first pattern

GreenWall ships as a desktop application built with Wails, so the normal path is to download the app rather than build it. The README says to make sure Git is installed, download the app, open it, and obtain a Personal Access Token so you can sign in. It points to docs/githubtoken_en.md for the token steps. On Windows and Linux the README says to download and run the application directly.

On macOS the app is not signed, so the first launch can hit a security restriction. The README gives these commands, and notes you do not need all of them, trying them in order and stopping when one works:

cd the-directory-where-green-wall.app-is-located
sudo xattr -cr ./green-wall.app
sudo xattr -r -d com.apple.quarantine ./green-wall.app

The README warns that these commands only modify file attributes and will not launch the app; you still double-click it afterwards. Once signed in, the README says your avatar and name appear in the upper-left corner. From there you drag across the calendar to paint, and when the design looks right you click Create Remote Repo, edit the repository name and description, choose public or private, and press Generate & Push to have the app create and push the repository.

If you would rather build it from source, the development guide lists Go 1.24+, Node.js v22+, and Git as prerequisites, and installs the Wails CLI at a pinned version:

go install github.com/wailsapp/wails/v2/cmd/[email protected]
git clone https://github.com/zmrlft/GreenWall.git
cd GreenWall
cd frontend && npm install

The repository's go.mod requires github.com/wailsapp/wails/v2 v2.11.0, which is ahead of the v2.10.2 CLI version named in the README. That mismatch is worth noticing before you file a build problem. Building is wails build, and the README says the output lands in build/bin/.

The delay is the real constraint

The most important sentence in the README is the heads-up that GitHub may take anywhere from 5 minutes to 2 days to show the contributions on your profile. That range is not a bug in GreenWall. It is how GitHub's contribution indexing behaves, and it means the tool's feedback loop is fundamentally slow. You cannot paint, push, and immediately confirm the result on your profile.

The README suggests a workaround that also happens to be the sensible default: keep the repository private and enable Include private contributions in your profile settings, so the repository contents stay hidden while the contribution streak still counts. That keeps the pattern visible without publishing a repository full of generated commits.

There is a second failure mode that the README does not document: nothing describes rollback. Once the commits are pushed, the documentation is silent on deleting them, reverting the repository, or cleaning up the contribution graph afterwards. Anyone who wants a reversible experiment should assume they are doing that part by hand.

The tool is also the wrong choice if the pattern needs to be precise at the cell level. A 7 by 52 grid is 364 cells, and the README's advice to crop or smooth a noisy background before raising the threshold is really an admission that a busy image has nowhere to go in that resolution.

GreenWall against a scripted commit generator

The obvious alternative is a small script that writes dated commits itself, using something like git commit with a backdated GIT_AUTHOR_DATE and a loop over the target dates. The difference in approach is where the image processing lives. A script leaves that entirely to you: you decide the grid, compute the per-cell commit counts, and handle the push. GreenWall's contribution is the interactive editor around that step, with a live calendar preview, a brush and eraser, brush intensity for different shades of green, and a copy-and-paste mode where you drag to select an area, press Ctrl+C, and the copied pattern follows the mouse until you left-click or press Ctrl+V to place it.

That editor is the reason to pick GreenWall over a script. If you already know the exact commit counts you want, a script is smaller and gives you a diff you can review before pushing. If you are iterating on how an image reads at seven rows tall, the preview and the threshold controls save a lot of guessing. The trade-off is that GreenWall's output is a repository you did not write by hand, created through the app, and the README does not describe a dry-run mode that would let you inspect the commits before they are pushed.

Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-03-28, which is also the date of the v0.7.5 release. Before that, v0.7.4 landed on 2026-01-31 and v0.7.3 on 2025-12-07, so the release cadence through that period was roughly every one to two months. The README records that the project was recommended by YiFeng Ruan and featured in Tech Enthusiast Weekly Issue 372 in early November, then covered in GitHub Weekly Hotspots Issue 93 in mid-November, and selected as an interesting project by HelloGitHub in December.

GreenWall is MIT licensed, which is permissive and places few obligations on anyone reusing the code; the LICENSE file at the repository root is the authoritative text. The practical upgrade cost is low for users of the prebuilt app and higher for anyone building from source, because the Wails CLI version in the README and the Wails version in go.mod are not the same, and the frontend is a separate npm install under frontend/. Expect to re-run npm install after pulling changes that touch dependencies.

Editorial conclusion

GreenWall fits people who want a specific image to appear on their own contribution calendar and are willing to wait for GitHub to catch up. It is the wrong tool for anyone who needs the pattern to appear within minutes, anyone who cannot generate a personal access token, or anyone who wants the commits to carry meaningful history. Before committing to it, check the macOS launch behaviour on your own machine, confirm whether your profile shows private contributions, and look at the most recent release notes for changes to the rendering controls.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes