Level Up Your GitHub Profile with a 3D Contribution Calendar

Want a dynamic and visually stunning GitHub profile? This guide reveals how to create a captivating 3D contribution calendar that showcases your coding activity.

Why Create a 3D GitHub Contribution Calendar?

• Stand Out: Make a memorable first impression with a unique profile.
• Showcase Activity: Highlight your contributions in an engaging way.
• Personalize Your Brand: Customize the calendar to match your style.

Easy Setup with GitHub Actions: Basic Guide

This action automates the generation of a 3D contribution calendar on your GitHub profile image, committing the changes directly to your repository.

Step 1: Create a Special Repository

Name it the same as your username. For example, if your username is "octocat," create a repository named "octocat/octocat". This repo will house your profile README.

Step 2: Create a Workflow File: .github/workflows/profile-3d.yml

This file automates the 3D contribution calendar generation. You can customize the schedule to run at your preferred time.

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

Key points:

• The schedule triggers the action daily. Adjust the cron expression for your desired time (UTC).
• If you want to include private repository contributions, register a personal access token (PAT) with appropriate permissions as a secret (e.g., MY_PERSONAL_ACCESS_TOKEN) and use it for GITHUB_TOKEN. Remember, user-created secrets can not start with prefix GITHUB_.
• The GitHub Actions GITHUB_TOKEN secret can be used as is if you only want to generate a calendar for public contributions.

Step 3: Manually Launch the Action (Optional)

Go to "Actions" -> "GitHub-Profile-3D-Contrib" -> "Run workflow" to trigger the action immediately.

Step 4: Add the Image to Your README.md

Reference the generated image in your README.md file:

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

Available Image Styles:

• 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 SETTING_JSON)

Advanced Customization

Environment Variables:

• GITHUB_TOKEN (required): Access token.
• USERNAME (required): Target username.
• MAX_REPOS (optional, default 100): Maximum number of repositories to consider (since v0.2.0).
• SETTING_JSON (optional): Path to a custom settings JSON file for advanced customization (since v0.6.0).
• GITHUB_ENDPOINT (optional): Custom GitHub GraphQL endpoint (since v0.8.0).
• YEAR (optional): Specify the year for past contribution calendars (since v0.8.0).

Schedule Timing Tips

The workflow file example uses "0 18 * * *" which translates to 18:00 UTC. Adjust this cron expression to your preferred time in UTC.

Local Usage

1. Set the GITHUB_TOKEN environment variable:

   export GITHUB_TOKEN=YOUR_PERSONAL_ACCESS_TOKEN
   

   Copy

2. Run the script with your GitHub username:

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

   Copy

   or

   npm run build
   node YOUR_USERNAME
   

   Copy

License

This project is under the MIT License.