How to Add a 3D Contribution Graph to Your GitHub Profile README

The github-profile-3d-contrib project generates an isometric SVG visualization of your GitHub contribution calendar. Instead of the flat green-square grid on your profile page, it renders the same data as a 3D landscape where taller columns represent days with more contributions. The result is visually dramatic, especially for developers with high-activity periods — a sprint of daily commits creates a skyline of tall bars.

The image is generated by a GitHub Action that runs daily, commits the SVG to your repository's profile-3d-contrib directory, and can be referenced in your README with a standard image tag. Multiple themes are supported including both day and night variants.

Create .github/workflows/profile-3d.yml in your GitHub profile repository:

name: GitHub-Profile-3D-Contrib
on:
  schedule:
    - cron: '0 18 * * *'
  workflow_dispatch:
permissions:
  contents: write
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: yoshi389111/github-profile-3d-contrib@0.7.1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          USERNAME: ${{ github.repository_owner }}
      - run: |
          git config user.email action@github.com
          git config user.name GitHub Action
          git add -A
          git commit -m 'generate 3d contribution'
          git push

After the first run, add to your README:

![3D Contribution Graph](profile-3d-contrib/profile-night-rainbow.svg)

The Action generates multiple theme files — check the profile-3d-contrib directory after the first run to see all available options.

The Action generates multiple SVG variants in different themes automatically. After the first successful run, check your repository's profile-3d-contrib/ directory for all generated files. Common theme files include:

• profile-night-rainbow.svg — dark background with rainbow-colored bars
• profile-night-green.svg — dark background with GitHub green bars
• profile-south-season-animate.svg — animated version with seasonal coloring
• profile-gitblock.svg — block-style 3D representation
• profile-night-view.svg — dark with blue/purple accents

Use the animated variants sparingly — they add visual interest but significantly increase file size, which can slow profile load times. The non-animated night-rainbow version is the most commonly used choice.

If the workflow fails with a permissions error, ensure the workflow YAML includes permissions: contents: write. This permission allows the Action to commit the generated SVG files back to your repository. Without it, the commit step will fail with a 403 error.

If the graph generates but appears mostly flat (few tall bars), this reflects your actual contribution history for the past year. The visual is more impressive with consistent daily or near-daily contribution activity — sparse contribution periods render as flat sections.

If the image path in your README shows as broken, verify the exact file name matches what the Action created. Run the workflow manually from the Actions tab, then check the profile-3d-contrib/ directory in your repository to see the exact filenames generated.