GitHub Paint

a GitHub action to draw text in your GitHub contributions graph.

Usage

Note

See action.yml for additional configuration documentation

Create a GitHub Personal Access Token (docs) with repo, read:user, user:email, and delete_repo permissions (used to clean up previous repo commits and automatically retrieve necessary user information).
In a new or existing repository, store the access token as a GitHub secret under the key GH_PAINT_PAT

Create a workflow to invoke the action:

.github/workflows/github-paint.yml

name: Generate GitHub contributions graph
on: 
  schedule:
    - cron: '0 0 * * *' # run daily if you care about having the graph coloring up-to-date
  workflow_dispatch: # or just run it manually every now and again
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: tbrockman/github-paint@latest # or choose a specific semver (ex. tbrockman/github-paint@v1.0.1)
      with:
        text: theo.lol # basic ascii chars supported
        token: ${{ secrets.GH_PAINT_PAT }}
        # inverse: false # invert pixel color (darker <-> lighter)
        # git_email: 'abc@example.dev' # set a specific email for git author attribution (defaults to token user primary email)
        # git_name: theo # choose an alternate name for git author contribution (defaults to token user name)
        # repo: 'github-painted' # destination repository for the filler commits
        # visibility: public # visibility of created repository (for instance, if using github enterprise in a private org) 
        # start: 2020-01-01 # start of drawing window
        # end: 2025-12-12 # end of drawing window
        # force_date: false # skip date any rounding, force use of specified dates
        # repeat: false # repeat text as much as possible over the window
        # separator: "|" # what to use as a separator when repeat=true
        # padding: (0,0,0,0) # (top,right,bottom,left) padding to add to the window (will clip content if necessary)
        # valign: center # text vertical alignment (top, center, bottom)
        # halign: center # text horizontal alignment (left, center, right)
        # dry_run: false # whether to actually perform write actions (manage commits or repos)

Execute the workflow (or wait for the cron to trigger)

Development

Prerequisites

Clone the repo:

git clone https://github.com/tbrockman/github-paint

Create a virtual environment:

python -m venv env

Activate the environment:

Linux/MacOS

source env/bin/activate

Windows

./env/Scripts/activate.ps1

Install the dependencies:

pip install -r requirements.txt

Run the CLI:

python main.py --help