GitHub Paint

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

Usage

Note

See action.yml for additional configuration documentation

1. 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).

2. In a new or existing repository, store the access token as a GitHub secret under the key GH_PAINT_PAT

3. 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)

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

Development

Prerequisites

• python
• gh cli

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