Building a Git Contribution Bot with GitHub Actions: Automating Your Green Squares

Ever looked at your GitHub profile and felt disappointed by the sparse green squares in your contribution chart? While genuine contributions are always best, sometimes you want to maintain activity during quiet periods or experiment with automation. This guide explores building a Git contribution bot using GitHub Actions that randomly generates commits to keep your contribution streak alive.

⚠️ Disclaimer: This is for educational purposes and experimentation. Authentic contributions through real projects are always more valuable than automated commits.

Understanding GitHub's Contribution Chart

Before diving into the automation, let's understand what counts as a contribution on GitHub:

What Counts as Contributions:

• Commits to the default branch of a repository you own
• Pull requests opened in any repository
• Issues opened in any repository
• Code reviews on pull requests
• Discussions started or participated in

What Doesn't Count:

• Commits to non-default branches (unless merged)
• Commits to forked repositories (unless you're the original owner)
• Commits made with unverified email addresses
• Commits older than one year
• Commits made to private repositories (unless you enable private contributions)

Key Requirements for Commit Contributions:

1. Email Verification: Your commit email must match a verified email in your GitHub account
2. Repository Ownership: You must own the repository or be a collaborator
3. Default Branch: Commits must be made to the repository's default branch
4. Timing: Only commits from the past year appear on your chart

The Contribution Bot Architecture

Our bot consists of two main components:

1. GitHub Actions Workflow - Automated scheduled execution
2. Bash Scripts - Logic for generating commits

GitHub Actions Workflow

name: Contribution Bot
on:
  schedule:
    - cron: '0 */6 * * *' # Runs every 6 hours
  push:
    paths:
      - 'trigger.txt' # Manual trigger option
jobs:
  push_to_repository:
    runs-on: [ubuntu-latest]
    steps:
      - uses: actions/checkout@v2
        with:
          token: ${{secrets.GH_TOKEN}}
      - name: Push to repository
        run: |
          COIN_FLIP=$(($RANDOM % 2))
          echo $COIN_FLIP
          if [ $COIN_FLIP -eq 1 ];then
            git config user.name ${{ secrets.GH_USER }}
            git config user.email '${{ secrets.GH_USER }}@users.noreply.github.com'
            COMMIT_MESSAGE=$(date "+%F %H:%M")
            rm file.txt
            echo "${COMMIT_MESSAGE}" >> file.txt
            git add .
            git commit -m "I am a productive developer ${COMMIT_MESSAGE}"
            git push
          fi

Key Features Explained:

1. Dual Trigger System:

• Scheduled: Runs automatically every 6 hours using cron syntax
• Manual: Triggers when trigger.txt file is modified

2. Randomization:

COIN_FLIP=$(($RANDOM % 2))

Uses a coin flip (50% chance) to decide whether to make a commit, creating natural-looking patterns.

3. Dynamic Content:

COMMIT_MESSAGE=$(date "+%F %H:%M")
echo "${COMMIT_MESSAGE}" >> file.txt

Generates unique content for each commit using timestamps.

Advanced: Historical Contribution Generation

For more comprehensive contribution history, the main.sh script can backfill historical commits:

#!/bin/bash
current_date="$(date -v1m -v1d -v+7y +%s)"
stop_date=$(date -v1m -v1d -v+8y +%s)"

until [[ $current_date -gt $stop_date ]]; do
    echo "$current_date"
    converted_date="$(date -r $current_date)"
    echo "$converted_date"
    echo "$converted_date" > file.txt
    git add .
    GIT_AUTHOR_DATE="$converted_date" GIT_COMMITTER_DATE="$converted_date" git commit -m "$converted_date"
    current_date="$(gdate -d "$converted_date + 1 day" +%s)"
done

Historical Script Features:

1. Date Manipulation:

• Starts from a specific historical date
• Increments day by day until reaching the end date
• Uses date command variations for macOS compatibility

2. Git Date Override:

GIT_AUTHOR_DATE="$converted_date" GIT_COMMITTER_DATE="$converted_date" git commit -m "$converted_date"

Sets both author and committer dates to create commits that appear in the past.

Setup Instructions

1. Repository Setup

Create a new repository specifically for your contribution bot:

mkdir git-contribution-bot
cd git-contribution-bot
git init
echo "Contribution Bot Repository" > README.md
echo "$(date)" > file.txt
git add .
git commit -m "Initial commit"

2. GitHub Secrets Configuration

Navigate to your repository settings and add these secrets:

• GH_TOKEN: Personal Access Token with repo permissions
• GH_USER: Your GitHub username

Creating a Personal Access Token:

1. Go to GitHub Settings → Developer settings → Personal access tokens
2. Generate new token with repo scope
3. Copy the token immediately (you won't see it again)

3. Workflow File Creation

Create .github/workflows/contribution-bot.yml with the workflow code above.

4. Email Configuration

Ensure your commits count toward contributions:

git config user.email "your-verified-email@example.com"

Or use GitHub's noreply email:

git config user.email "username@users.noreply.github.com"

Customization Options

Frequency Adjustment

Modify the cron schedule for different frequencies:

# Every hour
- cron: '0 * * * *'

# Every day at 9 AM
- cron: '0 9 * * *'

# Every weekday at 6 PM
- cron: '0 18 * * 1-5'