Level Up Your GitHub Profile with a 3D Contribution Calendar

Transform your GitHub profile into a visually engaging masterpiece! This guide reveals how to create a stunning 3D contribution calendar using the github-profile-3d-contrib action, boosting your profile's appeal and showcasing your activity in a unique way.

Why Use a 3D Contribution Calendar?

• Stand Out: Differentiate your profile from the crowd with a captivating visual representation of your coding activity.
• Highlight Your Contributions: Emphasize your dedication and consistent work on projects.
• Increase Engagement: Attract more attention to your profile and encourage exploration of your repositories.

Step-by-Step Guide: Setting Up Your 3D Contribution Calendar

Follow these simple steps to generate and display your 3D contribution calendar:

Step 1: Create a Special Repository

Your GitHub username needs its own Repo! Create a new repository with the same name as your GitHub username (e.g., yourusername/yourusername). This is where the magic happens!

Step 2: Create a Workflow File

This file automates the 3D generation process like a tireless robot!

1. Create a directory .github/workflows in your repository.
2. In that directory, create a file named profile-3d.yml.
3. Paste the following code into the file:

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

Important Notes:

• Modify the cron value in the schedule section to adjust the execution time. The example runs at 18:00 UTC (which is 03:00 JST).
• The USERNAME variable automatically uses your repository owner name.
• This setup uses the default GITHUB_TOKEN for public repositories.

Step 3: Tweak Your Configuration (Optional)

Customize your 3D calendar to make it truly "you"!

• If you want to include private contributions and language information, you'll need to generate a personal access token with the appropriate permissions and store it as a secret in your repository settings (e.g., MY_PERSONAL_ACCESS_TOKEN). Ensure it does not start with GITHUB_.
• Then, update the workflow file like this:

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

Step 4: Manually Launch the Action

Kickstart the process!

1. Go to the "Actions" tab in your repository.
2. Select "GitHub-Profile-3D-Contrib."
3. Click "Run workflow."

Step 5: Add the Image to Your README.md

Show off your cool 3D calendar!

1. Find the generated image paths in your repository (e.g., profile-3d-contrib/profile-green-animate.svg).
2. Add the corresponding Markdown image tag to your README.md file:

![GitHub 3D Contribution Calendar](./profile-3d-contrib/profile-green-animate.svg)

Pro Tip: The action generates various styles. Experiment to find the one that you like the most!

Advanced Customization: Unleash the Power User Within!

• MAX_REPOS: Control the maximum number of repositories considered (default: 100).
• SETTING_JSON: Use a custom JSON file to fine-tune the appearance of your calendar (refer to the example settings in the repository).
• GITHUB_ENDPOINT: Specify a custom GitHub GraphQL endpoint, if needed.
• YEAR: Creates a calendar for a specific year (past calendars).

Example: Local Usage

You can run the script locally to test it. Set environment variable GITHUB_TOKEN and provide your username to the script to trigger the generation.

export GITHUB_TOKEN=YOUR_PERSONAL_ACCESS_TOKEN
node_modules/.bin/ts-node src/index.ts YOUR_GITHUB_USERNAME

Note: It is possible you might need to build the project with npm run build before running the script above.

Elevate Your GitHub Profile Today!

By following these steps, you can create a visually appealing and informative 3D contribution calendar that enhances your GitHub profile and showcases your coding activity. Start customizing your profile today!