Transform Your GitHub Profile with a 3D Contribution Calendar

Tired of the same old flat GitHub profile? Want to showcase your contributions in a visually stunning way? This guide shows you how to use the github-profile-3d-contrib action to create a dynamic, eye-catching 3D contribution calendar. Boost your profile's appeal and stand out from the crowd!

What is github-profile-3d-contrib?

This GitHub Action automatically generates a 3D visualization of your GitHub contribution activity, turning your profile into an interactive work of art.

Benefits:

• Visually Appealing: Dramatically improves your profile's aesthetics.
• Showcase Activity: Highlights your contributions in a unique format.
• Easy Integration: Simple setup using GitHub Actions.

Basic Setup: Creating Your 3D Profile

Here's how to quickly set up your 3D contribution calendar using GitHub Actions:

1. Create a Special Repository: Name it the same as your GitHub username. For example, if your username is "octocat," create a repository named "octocat/octocat." This is where your profile README lives.

2. Create a Workflow File: Add a .github/workflows/profile-3d.yml file to your repository with the following content:

   name: GitHub-Profile-3D-Contrib
   on:
     schedule: # 03:00 JST == 18:00 UTC
       - cron: "0 18 * * *"
     workflow_dispatch:
   jobs:
     build:
       runs-on: ubuntu-latest
       name: generate-github-profile-3d-contrib
       steps:
         - uses: actions/checkout@v4
         - uses: yoshi389111/github-profile-3d-contrib@latest
           env:
             GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN}}
             USERNAME: ${{ github.repository_owner}}
         - name: Commit & Push
           run: |
             git config user.name github-actions
             git config user.email [email protected]
             git add -A .
             if git commit -m "generated"; then
               git push
             fi
   

   Copy
   • Schedule: The cron setting determines when the action runs. "0 18 * * *" means 6:00 PM UTC daily. Adjust to your preferred time.

3. Manually Trigger: Go to your repository's "Actions" tab, select "GitHub-Profile-3D-Contrib," and click "Run workflow."

4. Add Image to README: In your README.md file, include the generated image using the following markdown:

   ![](./profile-3d-contrib/profile-green-animate.svg)
   

   Copy

Environment Variables: Customize Your Calendar

Fine-tune your 3D calendar with environment variables:

• GITHUB_TOKEN (Required): A GitHub access token. Use ${{ secrets.GITHUB_TOKEN }} for public repos. For private contributions, create a personal access token and store it as a secret (e.g., MY_PERSONAL_ACCESS_TOKEN). Then use ${{ secrets.MY_PERSONAL_ACCESS_TOKEN }}.
• USERNAME (Required): Your GitHub username, or the target user.
• MAX_REPOS (Optional): maximum number of repositories, default is 100.
• SETTING_JSON (Optional): Path to customized settings.
• GITHUB_ENDPOINT (Optional): Custom GitHub GraphQL Endpoint.
• YEAR (Optional): Target specific year for calendar.

GITHUB_TOKEN Explained

GitHub automatically creates a special GITHUB_TOKEN for actions. This token is sufficient for generating contribution calendars for public repositories.

Private Repository Access

To include private repository activity:

1. Enable "Include private contributions on my profile" in your GitHub profile settings.

2. Create a Personal Access Token with appropriate permissions. Remember, secrets cannot start with GITHUB_*.

3. Store the token as a repository secret (e.g., MY_PERSONAL_ACCESS_TOKEN).

4. Update your workflow file:

   env:
     GITHUB_TOKEN: ${{ secrets.MY_PERSONAL_ACCESS_TOKEN }}
     USERNAME: ${{ github.repository_owner}}
   

   Copy

Available 3D Calendar Styles

Choose from several pre-designed styles to suit your preference:

• profile-green-animate.svg
• profile-green.svg
• profile-season-animate.svg (Northern Hemisphere)
• profile-season.svg (Northern Hemisphere)
• profile-south-season-animate.svg (Southern Hemisphere)
• profile-south-season.svg (Southern Hemisphere)
• profile-night-view.svg
• profile-night-green.svg
• profile-night-rainbow.svg
• profile-gitblock.svg
• profile-customize.svg - If using a SETTING_JSON file

Advanced Usage

Explore EXAMPLES.md (linked in the original documentation) for more advanced customization options.

Local Usage (For Developers)

For local development and testing:

1. Set the GITHUB_TOKEN environment variable:

   export GITHUB_TOKEN=YOUR_PERSONAL_ACCESS_TOKEN
   

   Copy

2. Run the script:

   node_modules/.bin/ts-node src/index.ts YOUR_GITHUB_USERNAME
   

   Copy

   or

   npm run build
   node YOUR_GITHUB_USERNAME
   

   Copy

Licence

This project is released under the MIT License. (C) 2021 SATO, Yoshiyuki.