빠른 답변: GitHub Profile 3D Contrib란?
GitHub Profile 3D Contrib는 사용자의 기여 캘린더를 프로필용 3D 이미지로 바꾸는 GitHub Action입니다. 별도의 뷰어를 여는 대신 생성된 이미지를 같은 저장소에 커밋하므로 README에 최신 3D 기여 캘린더를 표시할 수 있습니다.
검색 의도는 GitHub City와 다릅니다. github profile 3d contrib를 찾는 방문자는 보통 workflow 파일, 프로필 README 이미지 경로, 안정적인 업데이트 일정을 원합니다. GitHub City를 찾는 방문자는 저장소를 수정하지 않고 사용할 수 있는 온라인 시각화 도구를 원하는 경우가 많습니다.
최종 결과를 GitHub 프로필 README에 넣으려면 profile-3d-contrib를 사용하세요. 브라우저에서 3D 도시를 빠르게 확인하거나 공유하려면 GitHub City를 사용하고, README 이미지·인터랙티브 도시·인쇄용 모델 중에서 선택하려면 3D 도구 비교를 확인하세요.
github profile 3d contrib 의도에서는 README 자동화, GitHub Actions, 생성 파일, 문제 해결이 이 페이지의 범위입니다. 사용자 이름을 입력해 온라인 3D 도시를 보려면 GitHub City를 사용하세요.
README를 망치지 않고 profile-3d-contrib 설정하기
공식 Action으로 시작하고 이미지가 프로필에 표시되기 전에 GitHub 관련 조건을 확인하세요. 작고 명확하며 수동으로 다시 실행하기 쉬운 설정이 가장 안전합니다.
특수 프로필 repository 만들기
GitHub username과 정확히 같은 이름의 public repository를 만듭니다.
workflow 파일 추가
.github/workflows/profile-3d.yml을 만들고 contents: write, GITHUB_TOKEN, username을 설정합니다.
한 번 수동 실행
첫 실행은 workflow_dispatch로 권한, token, YAML, 파일 누락 오류를 확인합니다.
생성 이미지 삽입
생성된 SVG 또는 PNG 경로를 README.md에 추가하고 branch, folder, 대소문자, 상대 경로를 확인합니다.
private contribution 설정 확인
private contribution은 프로필 설정에서 공개 요약을 허용한 경우에만 반영됩니다.
확인해야 할 workflow 파일과 설정
안정적인 profile-3d-contrib 설정은 작지만 여러 요소가 연결됩니다. workflow, 생성 이미지 폴더, README 경로, 프로필 설정을 하나의 체인으로 확인하세요.
Actions 로그에서는 이미지가 업데이트되는데 README에 나타나지 않는다면 generator보다 커밋된 경로, 브랜치, 캐시 또는 Markdown 참조가 원인인 경우가 많습니다.
| 파일 또는 설정 | 목적 | 확인할 점 |
|---|---|---|
| README.md | GitHub 프로필에 3D 캘린더를 표시합니다. | 커밋된 이미지와 경로, 대소문자가 일치해야 합니다. |
| .github/workflows/profile-3d.yml | 예약 또는 수동으로 generator를 실행합니다. | 쓰기 권한과 수동 trigger를 포함합니다. |
| 출력 폴더 | 생성된 SVG/PNG 파일을 저장합니다. | workflow 완료 후 파일이 커밋되었는지 확인합니다. |
| 프로필 설정 | private activity의 공개 요약을 제어합니다. | 표시하려는 경우에만 활성화합니다. |
| 워크플로 커밋 단계 | 생성된 SVG 또는 PNG 파일을 프로필 저장소에 다시 기록합니다. | 생성 이미지 파일만 커밋하고 빈 커밋과 캐시 파일 포함을 피하세요. |
profile-3d-contrib vs GitHub City vs GitHub Skyline
이 도구들은 모두 GitHub 기여 데이터를 사용하지만 해결하는 작업은 서로 다릅니다. 3D 기여 그래프라는 문구만 보고 선택하지 마세요.
profile-3d-contrib
프로필 README에 항상 보이는 이미지가 필요할 때 적합합니다. repository 설정과 Actions가 필요합니다.
GitHub City
YAML 없이 브라우저에서 username을 입력해 3D 도시를 즉시 탐색할 때 적합합니다.
GitHub Skyline
README 이미지나 브라우저 city보다 모델형 3D 출력이 필요할 때 적합합니다.
누락되거나 오래된 3D 이미지 문제 해결
생성된 이미지가 없다면 먼저 최신 Actions 실행 기록을 여세요. 실패했다면 token, 권한, YAML, rate limit 문제를 확인하고, 성공했지만 README 이미지가 없다면 출력 경로나 Markdown을 확인하세요.
이미지가 비어 보이면 공식 GitHub 기여 그래프와 비교하세요. GitHub 캘린더에 나타나지 않는 기여는 생성된 3D 이미지에도 보통 나타나지 않습니다. 커밋 문제는 커밋 그래프 체크리스트를 사용하세요.
이미지가 오래된 상태라면 예약 trigger의 시간대, 브랜치 보호, 커밋 단계의 push 여부, GitHub의 README 이미지 캐시를 확인하세요.
Actions는 성공했지만 이미지가 바뀌지 않으면 출력 파일 해시, README 이미지 경로, GitHub 또는 브라우저 캐시를 확인하세요.
프로필 전체 구조를 아직 정하는 중이라면 3D 이미지를 넣기 전에 GitHub profile README 템플릿 가이드를 먼저 확인하세요. 생성된 3D 이미지가 아닌 정적 README 위젯은 이 Actions workflow를 바꾸기보다 GitHub streak stats 가이드를 참고하세요.
README generator로 원시 Git 데이터를 디버깅하지 마세요
profile-3d-contrib는 GitHub가 공개하는 내용을 시각화합니다. 기여 수가 이상하면 3D generator를 바꾸기 전에 이메일 주소, 기본 브랜치, 비공개 기여 설정, fork 규칙을 먼저 확인하세요.
FAQ
profile-3d-contrib는 GitHub City와 같은가요?
아닙니다. profile-3d-contrib는 Actions로 README 이미지를 만들고, GitHub City는 브라우저용 인터랙티브 visualizer입니다.
GitHub Actions가 필요한가요?
일반 설정에서는 필요합니다. 이미지를 자동으로 다시 만들고 커밋하기 위해 Actions를 사용합니다.
3D 이미지가 비어 있는 이유는?
공식 contribution graph, workflow 권한, token, username, 출력 branch, README 경로를 확인하세요.
private contribution이 표시될 수 있나요?
GitHub가 공개 요약으로 허용한 범위만 반영됩니다.
빠르게 공유하려면 어떤 도구가 좋나요?
인터랙티브 보기에는 GitHub City, README 출력에는 profile-3d-contrib가 적합합니다.
github-profile-3d-contrib는 보통 어떤 파일을 생성하나요?
대부분 SVG 또는 PNG 형식의 3D 기여 캘린더 이미지를 생성해 프로필 저장소 폴더에 저장하고 README.md에서 참조합니다.
YAML을 바꾸기 전에 무엇을 확인해야 하나요?
프로필 저장소 이름, Actions 권한, 출력 폴더, 브랜치, README 경로, 사용자 이름, GitHub 공식 그래프의 활동 표시 여부를 확인하세요.