Level Up Your GitHub Profile with a 3D Contribution Calendar!

Tired of the same old GitHub profile? Want to showcase your coding activity in a visually stunning way? This guide shows you how to create a dynamic, 3D contribution calendar that will instantly grab attention using the github-profile-3d-contrib action. Prepare to impress visitors and boost engagement on your page!

Why a 3D GitHub Profile?

• Visually Appealing: Stand out from the crowd with a unique and eye-catching profile.
• Showcase Activity: Highlight your dedication and coding consistency in an engaging format.
• Increased Engagement: A captivating profile encourages visitors to explore your projects.

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

This action generates a 3D contribution calendar for your GitHub profile and automatically commits the changes to your repository. Here’s how to set it up:

Step 1: Create a Special Repository

• Naming Convention: Create a new repository with the same name as your GitHub username. For example, if your username is "octocat," name the repository "octocat/octocat." This is crucial for GitHub to recognize it as your profile repository.

Step 2: Create a Workflow File

1. File Location: Create a new file named profile-3d.yml within the .github/workflows/ directory of your repository.
2. Workflow Configuration: Copy and paste the code below into your profile-3d.yml file. This configures the GitHub Action to run daily and generate your 3D contribution calendar.

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

*   **Schedule:** The `cron: "0 18 * * *"` setting schedules the action to run daily at 18:00 UTC (which is 03:00 JST). Feel free to adjust the timing to your preference, but remember to use UTC.
*   **`GITHUB_TOKEN`:**  This uses GitHub's automatic token authentication. For public repositories, this is all you need!

Step 3: Manually Launch the Action

1. Navigate to Actions: In your repository, click on the "Actions" tab.
2. Run Workflow: Select the "GitHub-Profile-3D-Contrib" workflow and click "Run workflow."

The action will generate various 3D profile images in the profile-3d-contrib/ directory, including:

• profile-green-animate.svg
• profile-season-animate.svg
• profile-night-view.svg
• ...and more!

Step 4: Add the Image to Your README.md

1. Edit README.md: Open your README.md file in your repository.
2. Insert Image: Add an image tag to display your chosen 3D contribution calendar. For example:

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

Advanced Options & Customization

Including Private Contributions

To include activity from your private repositories:

1. Enable in Profile: In your GitHub profile settings, under "Public profile," check "Include private contributions on my profile."
2. Personal Access Token: Create a personal access token with the necessary permissions. Important: User-created secrets cannot start with GITHUB_.
3. Update Workflow: In your workflow file, replace ${{ secrets.GITHUB_TOKEN }} with ${{ secrets.YOUR_PERSONAL_ACCESS_TOKEN }}, where YOUR_PERSONAL_ACCESS_TOKEN is the name of your secret.

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

Configuration via SETTING_JSON

For more advanced customization, you can use a SETTING_JSON file. This allows you to fine-tune the appearance of your 3D calendar. Check the sample-settings/*.json files in the yoshi389111/github-profile-3d-contrib repository for examples and detailed options. Specify the path to your settings file using the SETTING_JSON environment variable in your workflow.

Specifying a Year

To generate a calendar for a previous year, use the YEAR environment variable. This is helpful if you want to showcase your past activity.

Environment Variables Recap

• GITHUB_TOKEN: (Required) Your access token.
• USERNAME: (Required) Your GitHub username.
• MAX_REPOS: (Optional) Maximum number of repositories to consider (default: 100).
• SETTING_JSON: (Optional) Path to your custom settings file.
• GITHUB_ENDPOINT: (Optional) Custom GitHub GraphQL endpoint.
• YEAR: (Optional) The year for which to generate the calendar. Example Usage

env:
  GITHUB_TOKEN: ${{ secrets.YOUR_PERSONAL_ACCESS_TOKEN }}
  USERNAME: yourusername
  MAX_REPOS: 50
  SETTING_JSON: settings.json
  YEAR: 2022

Get Creative!

With github-profile-3d-contrib, you can transform your GitHub profile into a captivating showcase of your coding journey. Experiment with different themes, customize the settings, and create a profile that truly reflects your style!