Contribution Graph Action

Maybe most of your coding happens on another version control host, like GitLab or Bitbucket. Maybe your company uses GitHub Enterprise but hasn't enabled unified contributions. Maybe you're looking for a new software development job and are worried that recruiters will prejudge you by your scarce contribution graph.
Or maybe you have other reasons. Whatever the case may be, you've come to the right place.

Quick start without leaving your browser ⚡

1. Create a new repo (preferably private unless you have no shame)
2. Click on Create a new file
   
3. In the Name your file... field, type in .github/workflows/main.yml
4. Paste in one of the YAML file contents below, depending on what you want to do. Be sure to update GIT_EMAIL.
5. Click the Commit new file button at the bottom of the page. You're all set!
   • Note that you must enable the option below in your contribution settings for private commits to count on the graph.

If you change your mind about these commits later, you can delete the repository and they'll disappear from your contribution graph.

Push a commit to GitHub once a day 🍺

# .github/workflows/main.yml

on:
  schedule:
  - cron: '0 12 * * *' # every day at noon

jobs:
  single-commit:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
    - uses: bcanseco/github-contribution-graph-action@v2
      env:
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        GIT_EMAIL: [email protected] # replace me

If you need help with cron job syntax, crontab guru is a great resource.

Backfill a year of commits whenever you push to GitHub 🍻

This rolls a pseudorandom number generator between 1 and 5 (inclusive) to determine how many commits to make per-day.

# .github/workflows/main.yml

on: push

jobs:
  backfill-commits:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
    - uses: bcanseco/github-contribution-graph-action@v2
      env:
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        GIT_EMAIL: [email protected] # replace me
        MAX_DAYS: 365
        MIN_COMMITS_PER_DAY: 1
        MAX_COMMITS_PER_DAY: 5

Keep reading for more cool stuff like:

• skipping weekends/weekdays
• backfilling specific time periods
• custom commit messages
• and more!

Environment variables 🌳

Key	Description	Default value	Required?
GITHUB_TOKEN	Allows this GitHub Action to make commits for you. Simply pass in ${{ secrets.GITHUB_TOKEN }}. Read more.		🟩
GIT_EMAIL	An email address associated with your GitHub account. Without this, contributions won't show up. Read more.		🟩
GIT_BRANCH	Must either be the default branch or gh-pages for contributions to show up.	The branch that triggered this Github Action
GIT_COMMIT_MESSAGE	The message to use for commits made by this GitHub Action.	chore(actions): empty commit for contribution graph
ORIGIN_TIMESTAMP	The unix timestamp to start commits on. If you set MAX_DAYS greater than 1, commits will be made on days prior to this time.	The current timestamp
MAX_DAYS	The maximum integer number of days to commit on. If you want to backfill a year of commits, set this to 365.	1
MIN_COMMITS_PER_DAY	The minimum integer number of commits to make per day (inclusive). Used by a pseudo-RNG.	1
MAX_COMMITS_PER_DAY	The maximum integer number of commits to make per day (inclusive). Used by a pseudo-RNG.	1
INCLUDE_WEEKDAYS	A boolean indicating whether or not to make commits on weekdays.	true
INCLUDE_WEEKENDS	A boolean indicating whether or not to make commits on weekends.	true
FORCE_PUSH	A boolean indicating whether or not to force push. WARNING: Setting this to true will clear out your repo on each run!	false

Advanced environment variables 🧙‍♂️

There's also some advanced environment variables you can provide. Click here!

Only set these if you know what you're doing:

Key	Description	Default value	Required?
GIT_HOST	You may be able to override this to support a GitHub Enterprise environment.	github.com
GIT_SSH_COMMAND		ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no
GITHUB_ACTOR		Set by the GitHub Actions runner
GITHUB_REPOSITORY		Set by the GitHub Actions runner

How do I know this is secure? 🔒

Explore the code! It's tiny and there aren't many dependencies.

Speaking of dependencies, all production npm dependencies used by this GitHub Action are automatically audited for vulnerabilities. If the badge at the top of this README is green, you're good to go.

If you're still worried about malicious code in this repository, GitHub recommends always using a specific version of any GitHub Actions you add to your repositories. Read more.

- uses: bcanseco/github-contribution-graph-action@v2
+ uses: bcanseco/[email protected]

As far as data security, there's two sensitive pieces of data that this Action handles:

• GITHUB_TOKEN
• GIT_EMAIL

GITHUB_TOKEN 🔑

GitHub has a great article about the token. It's the standard way that all GitHub Actions interact with GitHub on your behalf. The permissions of this token are both short-lived and scoped to one repo only.

You don't need to create this secret yourself; GitHub handles that for you. All you need to do is provide the token in your workflow, job, or step:

env:
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Getting 403 errors? ❌

Make sure your token has write permission for the contents scope. If you're using the examples in this README, this is already done for you.

You can alternatively set this as a repo-level default:

GIT_EMAIL 📧

This GitHub Action requires an email associated with your GitHub account. If you provide a random or throwaway email, contributions won't show up on your GitHub profile. Read more.

Chances are, your email is already public if you're making commits with it. But if you're concerned about privacy, you can do either of the following:

• Add your email as a secret and pass it in the same way as the GITHUB_TOKEN
• Use your GitHub-provided noreply email address

Contribute 👪

PRs are welcome! Please read the contributing guide. This project is MIT licensed.