[기술 블로그] 개발자의 이력서는 살아있다: GitHub Profile & Actions 자동화 구축 가이드

1. 서론: 왜 GitHub 프로필인가? (Why Now?)

GitHub가 2020년에 공개한 Profile README 기능은

개발자의 기술 스택과 활동성,

그리고 센스까지 한눈에 보여줄 수 있는

강력한 동적 캔버스(Dynamic Canvas)입니다.

오늘 저는 제 GitHub 프로필(Reasonofmoon)을 뜯어고치면서

적용한 기술적 요소들을 공유하려 합니다.

GitHub Actions를 활용해

12시간마다 자동으로 업데이트되는

프로필을 구축하는 과정에 집중해 보았습니다.

2. 아키텍처 설계 (Architecture Design)

프로필 리뉴얼의 핵심 목표는 다음 세 가지였습니다.

1. 시각적 임팩트 (Visual Impact): 텍스트보다 먼저 눈길을 사로잡는 동적 헤더.

2. 데이터 기반 신뢰 (Data-Driven Trust): 말로만 "열심히 했다"고 하는 대신, 커밋 수와 사용 언어 통계 등 실제 데이터를 실시간으로 시각화.

3. 자동화 (Automation): 내가 자고 있는 동안에도 프로필이 최신 상태를 유지하도록 cron 잡을 통한 자동 갱신.

이 목표를 달성하기 위해 다음과 같은 오픈소스 도구와 워크플로우를 조합했습니다.

• Frontend: Markdown + HTML (레이아웃), Capsule Render (헤더 이미지)

• Data Visualization: GitHub Readme Stats (통계 카드), Shields.io (배지)

• Automation: GitHub Actions + Platane/snk (Contribution Graph Animation)

3. 구현 상세 (Implementation Details)

3.1. 레포지토리 초기화의 비밀

GitHub 프로필을 만들기 위해서는

본인의 유저네임과 똑같은 이름의 Public Repository를 생성해야 합니다.

제 경우 Reasonofmoon/Reasonofmoon 리포지토리를 생성했습니다.

이 리포지토리의 README.md 파일이 바로 프로필 메인 화면이 됩니다.

약간의 팁이 있다면, 이 리포지토리는 포트폴리오의 대문이므로

커밋 메시지 하나도 깔끔하게 관리하는 것이 좋습니다.

("Fix typo"가 10개씩 쌓여 있는 것은 좋지 않습니다.)

3.2. 살아 움직이는 헤더: Capsule Render

첫인상을 결정하는 헤더에는 Capsule Render API를 활용했습니다.

SVG를 동적으로 생성해주는 서버리스 API입니다.

<div align="center">

&nbsp; <img src="https://capsule-render.vercel.app/api?type=waving&color=gradient&height=250&section=header&text=Hello%20World!&fontSize=70&animation=fadeIn&fontAlignY=38&desc=I%20am%20Reason%20of%20Moon&descAlignY=55&descAlign=50"/>

</div>

• type=waving: 하단이 물결치는 모양을 만들어 부드러운 느낌을 줍니다.

• animation=fadeIn: 페이지 로드 시 텍스트가 서서히 나타나는 효과를 줍니다. 정적인 마크다운 문서에 생동감을 불어넣는 킬러 기능입니다.

• color=gradient: 단색보다는 그라데이션을 사용하여 모던한 UI 트렌드를 반영했습니다.

3.3. 데이터 시각화와 필터링 전략 (The 'C++' Issue)

github-readme-stats는 훌륭한 도구이지만,

가끔 원하지 않는 데이터가 노출될 때가 있습니다.

예를 들어, 저는 주로 AI와 Python 관련 프로젝트를 진행하지만,

과거에 잠깐 건드린 C++ 코드가 통계의 상위권을 차지하고 있었습니다.

이는 내 현재 전문분야를 왜곡할 수 있습니다.

따라서 API 호출 시 파라미터를 통해 데이터를 큐레이션(Curation) 했습니다.

![Top Langs](https://github-readme-stats.vercel.app/api/top-langs/?username=Reasonofmoon&layout=compact&theme=radical&hide=c%2B%2B,C%2B%2B,cpp&cache_seconds=0)

• &hide=c%2B%2B,cpp: 특정 언어를 숨깁니다. 여기서 중요한 점은 c++처럼 특수문자가 들어간 경우 URL 인코딩(%2B)을 정확히 해줘야 한다는 점입니다.

• &cache_seconds=0: 개발 및 디버깅 단계에서는 캐시 때문에 변경 사항이 바로 반영되지 않을 수 있습니다. 0으로 설정하여 즉시 반영을 확인한 후, 배포 시에는 제거하는 것이 서버 부하를 줄이는 매너입니다.

3.4. Contribution Snake Game: GitHub Actions 자동화

이 프로젝트의 하이라이트인 '커밋 먹는 뱀' 애니메이션입니다.

이는 단순한 이미지가 아니라,

내 커밋 히스토리(Contribution Graph) 데이터를 입력받아

SVG 애니메이션을 생성하는 프로세스입니다.

이를 위해 .github/workflows/snake.yml 파일을 생성하고

다음과 같이 워크플로우를 정의했습니다.

name: Generate Snake

on:

  schedule:

    # 매 12시간마다 자동 실행 (Cron Expression)

    - cron: "0 */12 * * *"

  

  # 수동 실행 가능 (디버깅용)

  workflow_dispatch:

  

  # main 브랜치에 푸시될 때마다 실행 (즉각 반영용)

  push:

    branches:

    - main

jobs:

  build:

    runs-on: ubuntu-latest

    steps:

      - uses: actions/checkout@v3

      - uses: Platane/snk@v3

        id: snake-gif

        with:

          github_user_name: ${{ github.repository_owner }}

          # 생성된 SVG 파일을 dist 폴더에 저장

          outputs: |

            dist/github-contribution-grid-snake.svg

            dist/github-contribution-grid-snake-dark.svg?palette=github-dark

      # 생성된 파일을 output 브랜치에 배포 (GitHub Pages 방식 활용)

      - uses: crazy-max/ghaction-github-pages@v3.1.0

        with:

          target_branch: output

          build_dir: dist

        env:

          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

[Troubleshooting & Insights]

처음에는 Snake 애니메이션이 보이지 않는 문제가 있었습니다.

원인은 GitHub Actions 권한(Permissions) 문제였습니다.

워크플로우가 리포지토리에 파일을 쓰고(push)

업데이트하려면 쓰기 권한이 필요한데,

보안상 기본값이 'Read only'로 되어 있는 경우가 많습니다.

• Solution: Settings > Actions > General > Workflow permissions에서 Read and write permissions를 활성화하여 해결했습니다. 자동화 스크립트가 403 Forbidden 에러를 뱉는다면 99%는 이 권한 문제입니다.

4. OS 환경 차이와 Git 트러블슈팅 (Windows vs Linux)

이번 작업은 Windows PowerShell 환경에서 수행되었습니다.

리눅스나 맥의 Bash 쉘에 익숙한 개발자들이

윈도우에서 겪는 흔한 실수가 바로

명령어 체이닝(Command Chaining) 연산자입니다.

• Bash/Zsh: command1 && command2 (앞 명령어가 성공하면 뒤 명령어 실행)

• PowerShell: && 연산자는 최신 버전(PowerShell 7+)에서만 지원되며, 구버전(Windows PowerShell 5.1 등)에서는 지원하지 않습니다.

저는 습관적으로 git add . && git commit...을 입력했고, The token '&&' is not a valid statement separator라는 에러를 맞닥뜨렸습니다.

해결책:

PowerShell 환경 호환성을 위해 세미콜론(;)을 사용하거나 (git add . ; git commit...), PowerShell 7을 설치하여 사용하는 것이 좋습니다. 사소해 보이지만, CI/CD 스크립트를 작성할 때 실행 환경(Runner)의 OS와 쉘 버전을 체크하는 것은 매우 중요합니다.

5. 결론: 퍼스널 브랜딩은 계속된다

이렇게 해서 제 GitHub 프로필은 24시간 내내 제 활동을 시각화하고,

방문자에게 브랜드 아이덴티티를 전달하는 역할을 수행하게 되었습니다.

Before: 단순히 코드를 저장해두는 창고 (Archive)

After: 기술 스택과 활동성을 증명하는 쇼룸 (Showroom)

이 작업은 하루면 충분합니다. 하지만 그 효과는 지속됩니다.

여러분도 지금 바로 README.md를 열고,

여러분만의 이야기를 코드로 작성해 보시기 바랍니다.

[Resource Links]

• My GitHub: https://github.com/Reasonofmoon

• GitHub Readme Stats: https://github.com/anuraghazra/github-readme-stats

• Capsule Render: https://github.com/kyechan99/capsule-render

#GitHubActions #Automation #PersonalBranding #Git #CI/CD