서론

GitHub 프로필 페이지에는 컨트리뷰션 그래프(contributions graph)가 있습니다. 잔디를 심을 때마다 조금 기분이 좋아지곤 하죠.

그래서 문득 "이 잔디를 기반으로 성장하는 다마고치 같은 것이 있다면, 자연스럽게 매일 커밋하고 싶어지지 않을까?"라는 생각이 들었고, AI와 함께 만든 것이 이 기사의 Commit Pet입니다.

다음과 같이 동작합니다.

Commit Pet의 리포지토리는 다음과 같습니다.

TL;DR

• GitHub의 잔디로 성장하는 도트 그래픽 펫을 만들고, 누구나 사용할 수 있는 GitHub Action으로 만들었다
• README는 JS가 동작하지 않으므로, SVG+SMIL 애니메이션으로 구동하며, 내용은 매일 PR(Pull Request)로 교체한다
• 잔디 데이터로부터 기분·레벨·연속 일수를 계산하고, 사용자 이름으로부터 색상을 결정한다
• 덤으로, 업데이트 PR에 GitHub Models를 사용하여 펫의 일기를 쓰게 했다

만든 것

한마디로 말하면, 프로필 README에 붙일 수 있는 한 장의 SVG 카드입니다.

다음은 기능 목록입니다.

기분 좋음／보통／배고픔／아픔. 잔디를 심지 않을수록 기운이 없어진다

[3종류의 캐릭터]

위에서부터, 슬라임(Puni)／고양이(Nya)／유령(Boo). 이름에 따라 색상이 결정되므로 몸의 색상도 제각각

구조

GitHub의 README는 새니타이즈(sanitize)되어 있어 <script>가 동작하지 않습니다. 붙일 수 있는 것은 <img로 읽을 수 있는 정적 파일뿐입니다. 따라서 겉모습은 SVG + SMIL 애니메이션(JS 불필요)으로 구동하고, 내용은 매일 새로 만들어 PR로 교체하는 구성으로 했습니다.

전체적인 흐름은 다음과 같습니다.

1. 컨트리뷰션 이력을 가져오기

GitHub의 잔디 데이터는 GraphQL API의 contributionsCollection에서 가져올 수 있습니다.

query($login: String!) {
user(login: $login) {
contributionsCollection {
...

2. 이력에서 "기분"을 결정하기

펫의 기분은 "마지막 커밋 이후 경과한 일수"로 결정합니다. 로직은 매우 단순합니다.

function moodFromDays(daysSinceLastCommit) {
if (daysSinceLastCommit === 0) return "happy"; // 오늘 커밋함
if (daysSinceLastCommit <= 2) return "content"; // 1~2일
...

레벨은 누적 컨트리뷰션을 단계별 임계값에 대입할 뿐이며, 연속 일수(streak)는 오늘부터 거슬러 올라가 연속으로 커밋한 날을 세는 것뿐입니다. 거창한 머신러닝(Machine Learning)은 전혀 사용하지 않았습니다. "수치를 보고 즐거울 수 있는 상태로 번역하는 것"에 모든 역량을 집중했습니다.

3. 색상은 사용자 이름으로 결정하기

모두가 같은 색이면 재미없으므로, 사용자 이름을 해시(FNV-1a)하여 색상(hue)으로 변환합니다.

// 사용자 이름 → 0~360의 색상. 같은 이름이면 매번 같은 색이 됨 (결정론적)
const hue = hueFromSeed(hashString(username));

이를 통해 "내 펫은 이 색상"이라는 정체성이 생깁니다. 기분이 좋지 않을 때는 채도를 낮추어 "기운 없음"도 표현했습니다 (아플 때는 상당히 탁한 색이 됩니다).

고안 포인트

1. "누구나 사용할 수 있는" 도구로 만들기

기왕이면 자신 외에도 사용할 수 있게 하고 싶었기에, GitHub Actions를 이용한 구조가 적합했습니다.

composite action으로 만들면, 로직 본체를 자신의 리포지토리에 둔 채로 이용자는 YAML 파일을 하나 추가하는 것만으로 사용할 수 있습니다.

이용자가 자신의 프로필 리포지토리에 두는 것은 이것뿐입니다.

name: Commit Pet
on: schedule:
...

uses: yukurash/commit-pet@v1

이라는 한 줄로 생성 로직 일체가 불러와집니다. 게다가 이용자의 Actions 실행 시간으로 동작하므로, 몇 명에게 사용되든 저의 비용은 제로입니다.

2. 업데이트는 PR로 전달하기

매일의 업데이트를 main

브랜치에 직접 커밋해도 되지만, 그렇게 하면 히스토리가 기계적인 커밋으로 가득 차게 됩니다. 그래서 peter-evans/create-pull-request를 사용하여 업데이트를 Pull Request (PR)로 제출하는 방식으로 만들었습니다. 내용을 확인한 뒤 머지(Merge)할 수 있고, auto_merge를 통해 자동으로 반영할 수도 있습니다.

3. AI에게 “펫의 일기”를 쓰게 했다

이 부분은 재미를 위한 요소지만, 개인적으로 가장 마음에 드는 부분입니다. PR 본문에 펫이 쓴 듯한 한 줄 일기를 실었습니다. 문장은 GitHub Models(GITHUB_TOKEN과 permissions: models: read만 있으면 사용할 수 있는 무료 AI)가 작성하도록 했습니다.

"오늘도 만나서 반가워! 5일 만이라서 조금 배고팠어🍙"

실제로 자동 생성된 PR 본문은 다음과 같습니다. github-actions[bot]가 그날의 펫의 기분에 맞춰 한 줄 메시지를 남겨줍니다.

사용 방법

대략 3단계로 이루어집니다.

• 프로필 리포지토리(yourname/yourname)를 준비하고, PR 생성을 허용하는 설정을 ON으로 한다.
• .github/workflows/commit-pet.yml을 배치하여 1회 실행한 뒤, 생성된 PR을 머지한다.
• 프로필의 README.md에 ![Commit Pet](commit-pet.svg)를 한 줄 추가한다.

Windows / Mac별 명령어가 포함된 자세한 절차는 리포지토리의 README에 적혀 있으니 그쪽을 참고해 주세요.

마치며

하고 있는 일은 "히스토리를 가져와서, 상태를 계산하고, SVG를 그려서, PR을 내보내는 것"일 뿐, 특별한 기술을 사용하지는 않았습니다. 그럼에도 프로필에 펫이 있으면 신기하게도 "오늘도 잔디를 심어볼까(commit 할까)"라는 기분이 듭니다.

괜찮으시다면 여러분의 프로필에도 한 마리 살게 해보세요.

🔗 리포지토리: https://github.com/yukurash/commit-pet

스타(Star)나 피드백을 주시면 펫과 함께 기뻐하겠습니다🐾

Discussion