How to Generate a 3D GitHub Contribution Calendar

What GitHub Profile 3D Contrib Generates

GitHub Profile 3D Contrib solves a presentation problem rather than a data-storage problem. GitHub already exposes a conventional contribution calendar, while this project renders a user's contribution graph as a collection of 3D SVG scenes for use in a profile README. The intended audience is a developer who maintains a GitHub profile repository and wants the generated graphic committed alongside the README.

The project is implemented primarily in TypeScript. Its package metadata identifies `axios`, `d3`, and `jsdom` as runtime dependencies, which points to a process that obtains GitHub information, lays out contribution data, and renders the result as an SVG-capable image. This mechanism is based on the repository layout and package manifest. The README does not expose the internal GraphQL query sequence or every rendering stage.

The Action does not merely create a temporary artifact for viewing in the Actions interface. Its documented workflow uses the Action and then runs `git add`, `git commit`, and `git push`, placing the generated files in the repository so they can be referenced through raw GitHub URLs. That design suits a profile README because the images remain part of the profile repository.

The GitHub Actions Data and Commit Flow

The documented setup separates generation from persistence. `actions/checkout@v5` first obtains the target profile repository. `yoshi389111/github-profile-3d-contrib@latest` then runs with `GITHUB_TOKEN` and `USERNAME`. `USERNAME` defaults in the sample to `${{ github.repository_owner }}`, so the repository owner's profile is targeted when the profile repository follows GitHub's matching-name convention.

The workflow grants `contents: write`, which is necessary for the final push shown in the README. After the Action produces files under `profile-3d-contrib/`, the commit step stages all changes. The conditional `git commit` prevents the job from failing when there is nothing new to commit, while `git push` publishes anything that changed. Scheduled execution runs daily by default, and `workflow_dispatch` allows an operator to trigger it manually.

The repository contains source under `src/`, tests under `spec/`, sample settings under `sample-settings/`, and a compiled entry point in `dist/`. `action.yml` is the GitHub Action interface. The package scripts use TypeScript, ESLint, Prettier, Jest, `ts-node`, and `ncc`, while `dist/index.js` is the package main entry. This is a conventional source-plus-bundled-distribution layout for a TypeScript Action, although the README does not describe every runtime function.

Creating the Profile Repository and Scheduled Workflow

First, create a public profile repository whose name matches your GitHub username. The README gives `octocat/octocat` as the example and links to GitHub's profile README documentation. The Action itself is then configured inside `.github/workflows/profile-3d.yml`.

The following is the first part of the documented workflow. It defines a daily schedule at 18:00 UTC, which the README equates to 03:00 JST, and also permits manual execution through `workflow_dispatch`.

name: GitHub-Profile-3D-Contrib

on:
  schedule: # 03:00 JST == 18:00 UTC
    - cron: "0 18 * * *"
  workflow_dispatch:

permissions:
  contents: write

Continue the file with the checkout and generation steps shown in the README. The `@latest` reference tracks the Action's published default rather than pinning a release.

jobs:
  build:
    runs-on: ubuntu-latest
    name: generate-github-profile-3d-contrib
    steps:
      - uses: actions/checkout@v5
      - uses: yoshi389111/github-profile-3d-contrib@latest
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          USERNAME: ${{ github.repository_owner }}

The final step configures the Git identity used by Actions, stages the repository, and pushes only when a commit was created.

      - 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

After saving the file, open `Actions`, select `GitHub-Profile-3D-Contrib`, and choose `Run workflow`. The README recommends running it once manually rather than waiting for the next scheduled execution.

Publishing the Generated SVG in a Profile README

A successful run creates several standard SVG files under `profile-3d-contrib/`. The documented outputs include green, season, south-season, night-view, night-green, and night-rainbow variants. Each scene family has an animated form where the README lists one. The repository demo uses `profile-gitblock.svg`, also among the standard outputs.

To publish one, reference its committed path through a raw GitHub URL. The README begins an example for the green version using `https://raw.githubusercontent.com/` followed by the owner, repository, branch, and generated file path. Because the workflow pushes SVG output to the profile repository, the README can use the committed file rather than calling the Action each time a profile page loads.

This architecture has a clear operational boundary. Rendering happens during the GitHub Actions run, not whenever somebody views the profile. The schedule determines when contribution data is refreshed. If the workflow fails, or if the Action produces no file change, the committed image can remain unchanged. The README does not describe a separate cache invalidation step or continuous rendering service.

A custom `SETTING_JSON` file changes the generation model. If that settings file omits the `fileName` property, the README states that the output is written as `profile-3d-contrib/profile-customize.svg`. The README does not enumerate every available property. It directs developers to `sample-settings/*.json` and `src/type.ts` for the schema and details.

Tokens, Private Contributions, and Repository Limits

The default workflow uses `${{ secrets.GITHUB_TOKEN }}`, which GitHub creates for the workflow. The README says this is sufficient for a calendar based on public repositories and can also support private contributions when the user's public profile setting includes them. The relevant GitHub setting is described as `Include private contributions on my profile` under `Public profile` and `Contributions & Activity`.

Additional private-repository activity requires a user-created access token registered as a secret and assigned to the Action's `GITHUB_TOKEN` environment variable. The workflow permission itself is not enough for that broader data set. GitHub prohibits user-created secret names beginning with `GITHUB_`, so the README uses `MY_PERSONAL_ACCESS_TOKEN` as an example.

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

The access scope therefore becomes an adoption decision. Public activity uses the automatically managed token. Additional private activity asks the maintainer to create and store a separate credential. The README does not specify exact token scopes, rotation steps, or token expiry policy, so it would be incorrect to claim that `secrets.GITHUB_TOKEN` and a personal token always expose identical data.

Repository collection also has a ceiling. `MAX_REPOS` limits the number of repositories and defaults to 100. `GITHUB_ENDPOINT` can point to a GraphQL endpoint for GitHub Enterprise activity, with `https://github.mycompany.com/api/graphql` given as the example. `YEAR` supports past calendars and is described primarily as a command-line option.

Why a Static SVG Differs from a Live GitHub Dashboard

A real alternative is GitHub's standard contribution calendar shown on a GitHub profile. It is already part of the platform and does not require this project to query contribution data, render SVG files, commit generated output, or run a scheduled Action. For someone who only needs GitHub's normal calendar, this Action adds infrastructure without changing the underlying contribution records.

The difference is presentation. GitHub Profile 3D Contrib converts the calendar into named visual scenes and stores them as SVG assets. Its generated variants can then appear directly in a profile README. That is useful when the goal is a custom profile composition. It is unnecessary when the requirement is simply to inspect recent activity.

Another alternative is a manually maintained profile graphic. That avoids token configuration and automated pushes, but it will not reflect new contributions unless somebody updates it. The Action replaces that manual step with scheduled generation, at the cost of credentials, Actions usage, generated commits, and eventual diffs when the SVG changes.

The project is therefore the wrong tool for real-time interaction. The documented update model is a daily schedule plus manual dispatch, not a browser-side live query. It also does not claim to provide analytics, searchable contribution data, or an export format other than the listed SVG images. Those features are outside the documented purpose.

Release Cadence, License, and Maintenance Cost

The repository is not archived, and its last push was on 2026-10-14. Recent releases include `v0.9.3` on 2026-06-15, `v0.9.2` on 2026-02-15, and `v0.9.1` on 2025-09-13. The documented sample tracks `@latest`, which means workflow behavior can change when a newer release becomes the Action's default. Engineers who need exact repeatability should inspect which release that reference resolves to and decide whether pinning is appropriate.

The package and repository are identified under the MIT license. That designation permits use and modification under the license's conditions, but this review does not interpret those legal terms or provide legal advice. The `LICENSE` file is the place to verify the exact text distributed with the project.

Maintenance cost includes more than installing the Action. Each scheduled run consumes GitHub Actions resources, may create a commit, and can update multiple SVG files. Maintainers also need to account for changes in GitHub authentication, GraphQL access, Node.js packaging, and the SVG scene settings. The repository's `CHANGELOG.md`, release history, settings examples, and TypeScript types are the project-specific references for those checks.

The test and build commands in `package.json` show the intended contributor tooling. A source change would normally pass through `npm run lint` and `npm test`, while `npm run build` cleans `dist`, compiles TypeScript, and packages the Action entry point. The README is primarily an Action usage guide and does not document a separate rollback procedure.

Editorial conclusion

Adopt this Action if you want a generated, 3D contribution graphic in a GitHub profile README and are comfortable granting repository write access. Do not adopt it if you need a dashboard, private analytics, or an image that updates continuously without a scheduled workflow. Verify first that the selected token exposes the intended contribution data, the generated SVG appears where expected, and the chosen `SETTING_JSON` configuration produces the required filename.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. yoshi389111/github-profile-3d-contrib on GitHub