Skip to content

Update README.md #28

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ricoswabe wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Update README.md #28

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
185 changes: 68 additions & 117 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,76 +1,77 @@
<p align="center">
<img width="150px" src="./.github/images/cover.png">
<img width="150px" src="./.github/images/cover.png" alt="Contribution Graph Action">
</p>

<h1 align="center">
Contribution Graph Action
</h1>
<h1 align="center">Contribution Graph Action</h1>

<p align="center">
<a href="https://github.com/bcanseco/github-contribution-graph-action/actions?query=workflow%3Abuild">
<img src="https://github.com/bcanseco/github-contribution-graph-action/workflows/build/badge.svg">
<img src="https://github.com/bcanseco/github-contribution-graph-action/workflows/build/badge.svg" alt="Build Status">
</a>

<a href="https://github.com/bcanseco/github-contribution-graph-action/actions?query=workflow%3Atests">
<img src="https://github.com/bcanseco/github-contribution-graph-action/workflows/tests/badge.svg">
<img src="https://github.com/bcanseco/github-contribution-graph-action/workflows/tests/badge.svg" alt="Tests Status">
</a>

<a href="https://github.com/bcanseco/github-contribution-graph-action/actions?query=workflow%3Aaudit">
<img src="https://github.com/bcanseco/github-contribution-graph-action/workflows/audit/badge.svg">
<img src="https://github.com/bcanseco/github-contribution-graph-action/workflows/audit/badge.svg" alt="Audit Status">
</a>

<a href="https://github.com/marketplace/actions/autopopulate-your-contribution-graph">
<img src="https://img.shields.io/badge/action-marketplace-orange?logo=github">
<img src="https://img.shields.io/badge/action-marketplace-orange?logo=github" alt="GitHub Marketplace">
</a>

<a href="https://github.com/bcanseco/github-contribution-graph-action/releases">
<img src="https://img.shields.io/github/v/release/bcanseco/github-contribution-graph-action.svg?logo=github">
<img src="https://img.shields.io/github/v/release/bcanseco/github-contribution-graph-action.svg?logo=github" alt="Latest Release">
</a>
</p>

> 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](https://docs.github.com/en/enterprise-server@latest/admin/configuration/configuring-github-connect/enabling-unified-contributions-for-your-enterprise). 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](https://twitter.com/jacobmparis/status/1265740598277025792). Whatever the case may be, you've come to the right place.
> Are you coding on another version control system like GitLab or Bitbucket? Perhaps your company uses GitHub Enterprise without enabling [unified contributions](https://docs.github.com/en/enterprise-server@latest/admin/configuration/configuring-github-connect/enabling-unified-contributions-for-your-enterprise). Or maybe you're searching for a new role and want to enhance your GitHub profile.
> Whatever your reason, this GitHub Action helps you fill your contribution graph effortlessly.

## Quick start without leaving your browser ⚡
---

1. [Create a new repo](https://github.com/new) (preferably private unless you have no shame)
1. Click on **Create a new file**
## 🚀 Quick Start Without Leaving Your Browser ⚡

1. [Create a new repository](https://github.com/new) (private is recommended unless you’re okay with the visibility).
2. Click **Create a new file**
![](./.github/images/create-new-file.png)
1. In the **Name your file...** field, type in `.github/workflows/main.yml`
3. In the **Name your file...** field, type `.github/workflows/main.yml`
![](./.github/images/name-new-file.png)
1. Paste in one of the YAML file contents below, depending on what you want to do. Be sure to update `GIT_EMAIL`.
1. 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.
![](.github/images/private-contributions.png)
4. Paste one of the YAML examples below (and don't forget to set `GIT_EMAIL`).
5. Click **Commit new file** to save changes.

> **Note:** Enable this option in your profile settings to ensure private contributions count.
> ![](./.github/images/private-contributions.png)

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

### Push a commit to GitHub once a day 🍺
---

### 🍺 Push a Commit to GitHub Once a Day

```yml
# .github/workflows/main.yml

on:
schedule:
- cron: '0 12 * * *' # every day at noon
- 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: you@youremail.com # replace me
- uses: bcanseco/github-contribution-graph-action@v2
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
GIT_EMAIL: you@youremail.com # Set your email
```

If you need help with cron job syntax, [crontab guru](https://crontab.guru/) is a great resource.
Need help with cron job syntax? Try [crontab guru](https://crontab.guru/).

---

### Backfill a year of commits whenever you push to GitHub 🍻
### 🍻 Backfill a Year of Commits When You Push to GitHub

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

```yml
# .github/workflows/main.yml
Expand All @@ -83,101 +84,51 @@ jobs:
permissions:
contents: write
steps:
- uses: bcanseco/github-contribution-graph-action@v2
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
GIT_EMAIL: you@youremail.com # replace me
MAX_DAYS: 365
MIN_COMMITS_PER_DAY: 1
MAX_COMMITS_PER_DAY: 5
- uses: bcanseco/github-contribution-graph-action@v2
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
GIT_EMAIL: you@youremail.com # Set your email
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](#github_token-). | | 🟩 |
| `GIT_EMAIL` | An email address associated with your GitHub account. Without this, contributions won't show up. [Read more](#git_email-). | | 🟩 |
| `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 🧙‍♂️

<details>

<summary>There's also some advanced environment variables you can provide. Click here!</summary>

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 | |
## 🌳 Environment Variables

</details>

## How do I know this is secure? 🔒

Explore the [code](src/index.js)! It's tiny and there aren't many dependencies.

Speaking of dependencies, all production npm dependencies used by this GitHub Action are [automatically audited](./.github/workflows/audit.yml) 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](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsuses).

```diff
- uses: bcanseco/github-contribution-graph-action@v2
+ uses: bcanseco/github-contribution-graph-action@2.0.0
```

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

* [`GITHUB_TOKEN`](#github_token-)
* [`GIT_EMAIL`](#git_email-)

### `GITHUB_TOKEN` 🔑

GitHub has [a great article](https://docs.github.com/en/actions/security-guides/automatic-token-authentication#using-the-github_token-in-a-workflow) 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:

```yml
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```
| Key | Description | Default Value | Required? |
|-----------------------|-------------------------------------------------------------------------------------------------|-----------------------------------------------------|-----------|
| `GITHUB_TOKEN` | Token for this Action to make commits. Use `${{ secrets.GITHUB_TOKEN }}`. [Read more](#github_token). | | 🟩 |
| `GIT_EMAIL` | Your GitHub-associated email address for contributions to appear. [Read more](#git_email). | | 🟩 |
| `GIT_BRANCH` | Branch for commits (default branch or `gh-pages`). | Triggering branch | |
| `GIT_COMMIT_MESSAGE` | Commit message used by this Action. | `chore(actions): empty commit for contribution graph` | |
| `MAX_DAYS` | Number of days to backfill commits. | `1` | |
| `MIN_COMMITS_PER_DAY` | Minimum commits per day (inclusive). | `1` | |
| `MAX_COMMITS_PER_DAY` | Maximum commits per day (inclusive). | `1` | |

#### Getting 403 errors? ❌
For advanced configuration, check out the [full list of variables](#advanced-environment-variables).

Make sure your token has [write permission for the `contents` scope](https://docs.github.com/en/actions/using-jobs/assigning-permissions-to-jobs). 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:
## 🔒 How Secure Is This?

![](./.github/images/token-permissions.png)
- **Code**: The [source code](src/index.js) is simple and transparent.
- **Dependencies**: All dependencies are [audited automatically](./.github/workflows/audit.yml) for vulnerabilities.
- **Versioning**: Always use a specific version of this Action for added security.
```yml
- uses: bcanseco/github-contribution-graph-action@2.0.0
```

### `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](https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-settings-on-your-profile/why-are-my-contributions-not-showing-up-on-my-profile#you-havent-added-your-local-git-commit-email-to-your-profile).
## 📧 `GIT_EMAIL`

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:
Your email must be associated with GitHub to count contributions. Use your GitHub-provided `noreply` email for privacy if needed. [More info](https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-settings-on-your-profile/why-are-my-contributions-not-showing-up-on-my-profile#you-havent-added-your-local-git-commit-email-to-your-profile).

* [Add your email as a secret](https://docs.github.com/en/actions/security-guides/encrypted-secrets#creating-encrypted-secrets-for-a-repository) and pass it in the same way as the `GITHUB_TOKEN`
* [Use your GitHub-provided `noreply` email address](https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/setting-your-commit-email-address#about-commit-email-addresses)
---

## Contribute 👪
## 👪 Contribute

PRs are welcome! Please read the [contributing guide](.github/CONTRIBUTING.md). This project is [MIT](LICENSE) licensed.
Contributions are welcome! Check out the [contributing guide](.github/CONTRIBUTING.md).
This project is licensed under the [MIT License](LICENSE).