GitHub GraphQL Contributions API: 기여 달력 조회

GitHub GraphQL Contributions API: 반환 데이터

애플리케이션에 스크린샷이 아니라 날짜와 수치가 필요하다면 GitHub GraphQL Contributions API로 프로필 기여 달력을 읽을 수 있습니다. 사용자 로그인 이름을 지정하고 명확한 기간의 contributionsCollection을 요청한 다음 contributionCalendar를 선택합니다. 결과에는 전체 합계와 개별 기여 날짜가 들어 있는 주별 목록이 포함됩니다.

유용한 일별 레코드에는 날짜와 contributionCount가 포함됩니다. color와 weekday는 달력 모양을 재현하는 데 쓸 수 있고, totalContributions는 요청한 기간의 합계를 제공합니다. 이 값은 프로필에 표시되는 기여 활동을 설명합니다. 저장소 커밋 기록이나 완전한 감사 로그가 아니며, 앱에서 모든 비공개 활동을 볼 수 있다는 뜻도 아닙니다.

GitHub 문서에 따르면 비공개 및 내부 저장소의 기여 내역은 선택 권한인 read:user scope가 있어야 포함됩니다. 제품에 꼭 필요할 때만 이 접근 권한을 요청하고, 그렇지 않다면 토큰 권한을 더 좁게 유지하세요.

요청은 GitHub API endpoint로 보내는 GraphQL POST이며 인증이 필요합니다. 토큰은 서버나 로컬 환경 변수에 보관하고 필요한 접근 권한만 사용하세요. 브라우저 JavaScript, 공개 저장소 또는 공유 쿼리 예제에 비밀 값을 넣으면 안 됩니다.

GitHub GraphQL Contributions API 요청 만들기

GitHub GraphQL endpoint는 https://api.github.com/graphql입니다. Authorization bearer token과 query, variables가 담긴 JSON 본문을 포함해 POST 요청을 보냅니다. 쿼리 문자열과 변수 값을 분리하면 다른 사용자 이름이나 날짜 범위로 검토하고 테스트하고 재사용하기 편합니다.

이 예제는 저장소 커밋을 나열하는 대신 프로필 달력을 선택합니다. 달력 화면에 필요한 합계, 주 목록, 주별 기여 날짜만 요청합니다. 연간 합계만 필요하다면 totalContributions만 요청하고 중첩된 달력 필드는 생략할 수 있습니다.

GraphQL은 JSON 응답 envelope를 반환합니다. 데이터가 있다고 가정하기 전에 HTTP 상태와 최상위 errors 배열을 함께 확인하세요. 응답에 유용한 데이터와 GraphQL 오류가 동시에 들어올 수 있으므로 개발 중에는 오류 메시지와 데이터 경로를 따로 기록하세요.

쿼리와 변수

query UserContributionCalendar($login: String!, $from: DateTime!, $to: DateTime!) {
  user(login: $login) {
    contributionsCollection(from: $from, to: $to) {
      contributionCalendar {
        totalContributions
        weeks {
          contributionDays {
            date
            contributionCount
            color
            weekday
          }
        }
      }
    }
  }
}

{
  "login": "octocat",
  "from": "2026-01-01T00:00:00Z",
  "to": "2026-02-01T00:00:00Z"
}

POST JSON 본문에 쿼리 문자열과 variables 객체를 넣으세요. 실제 토큰은 이 예제에 넣지 말고, 필드를 더 추가할 때는 공식 schema를 확인하세요.

기여 달력 필드 읽기

응답 경로는 data.user.contributionsCollection.contributionCalendar입니다. 코드에서는 각 단계를 선택 값으로 다루세요. 사용자를 찾지 못하거나 인증 계정에서 필드를 사용할 수 없거나 응답에 오류가 포함될 수 있습니다. 중첩 속성에 접근하기 전에 응답을 확인하세요.

totalContributions는 선택한 기간의 합계입니다. weeks는 달력을 열 단위로 묶고 contributionDays의 각 항목은 날짜 하나를 나타냅니다. contributionCount는 그날의 활동 수치이고 date는 달력 날짜입니다. weekday는 요일을 숫자로 나타내며 1은 월요일입니다. color는 16진수 값이며 달력에서 더 어두운 색일수록 기여가 많음을 뜻합니다. 날짜와 수치는 지속적으로 보관할 데이터로, 색상은 표시용 메타데이터로 취급하세요.

일별 레코드로 표, 히트맵 또는 차트를 만들 수 있습니다. 기여 수가 0인 날짜도 유지하세요. 제거하면 날짜가 밀려 활동이 잘못 표시될 수 있습니다.

명확한 날짜 범위 선택

from과 to에는 ISO 8601 형식의 DateTime 값을 전달합니다. UTC 경계를 명시하면 정기 보고서를 재현할 수 있고 사용자, 서버, 차트가 서로 다른 시간대를 쓸 때 생기는 하루 차이 오류를 줄일 수 있습니다. 시간을 변환하기 전에 GitHub 달력 날짜와 사용자 현지 시간대 중 제품에서 어떤 기준으로 날짜를 묶을지 정하세요.

기간이 이동하는 보고서라면 정확한 시작과 끝을 계산해 저장하세요. 비교 기간의 길이를 같게 하고, 긴 이력은 한 번의 응답이 무제한 보관소인 것처럼 다루지 말고 범위가 제한된 구간으로 나누세요.

UTC 자정 무렵에 시작하거나 끝나는 범위와 활동이 보이지 않는 범위를 각각 테스트하세요. 반환된 합계와 날짜 목록은 요청한 정확한 기간과 일치해야 합니다. 합계가 0인 것도 유효한 결과이며 쿼리 실패를 뜻하지 않습니다.

차트를 만들기 전 응답 정규화

간결한 내부 모델을 만들면 API 응답을 차트, CSV 내보내기 또는 예약된 snapshot에서 활용하기 쉽습니다. 주별 배열을 하나의 정렬된 목록으로 펼치고 날짜와 수치를 보존하며 color나 weekday는 표시 기능에서 필요할 때만 유지하세요. 객체 key의 우연한 순서에 기대지 말고 펼친 뒤 날짜순으로 정렬합니다.

서비스 환경에서는 날짜를 해석할 수 있고 수치가 유한한 0 이상의 값인지 확인하세요. 화면을 그리기 전에 사용자 없음, 빈 컬렉션, 중복 날짜, 일부 GraphQL 데이터, rate limit 응답을 어떻게 처리할지 정합니다. 데이터가 없을 때 분명한 빈 상태를 보여주는 편이 달력을 깨뜨리거나 누락값을 조용히 0으로 바꾸는 것보다 낫습니다.

프로필 달력은 저장소 이력과 다른 질문에 답합니다. 프로필 그래프의 규칙이나 빈 사각형은 기여 그래프 규칙 안내를, 특정 저장소의 기록은 커밋 기록 안내를 참고하세요.

주 배열을 일별 레코드로 펼치기

const days = (calendar.weeks || [])
  .flatMap((week) => week.contributionDays || [])
  .map(({ date, contributionCount, color, weekday }) => ({
    date,
    count: Number(contributionCount),
    color,
    weekday,
  }))
  .sort((a, b) => a.date.localeCompare(b.date));

이 단계 전에 달력을 검증하고 누락된 데이터를 명시적으로 처리하세요. 시간 순서를 맞추도록 기여 수가 0인 날짜도 보존합니다.

• GitHub 기여 그래프 규칙 안내 — 프로필 기여 계산 규칙과 누락된 사각형을 확인할 때 이용하세요.
• GitHub 커밋 기록 안내 — 커밋, 파일 이력, 저장소 기간을 확인할 때 이용하세요.
• GitHub City 사용해 보기 — 원본 그래프를 확인한 다음 공개 기여 패턴을 3D 시각화로 살펴보세요.

GraphQL 응답과 제한 문제 해결

요청이 실패하면 HTTP 상태, 응답 JSON, errors 배열을 함께 살펴보세요. 잘못된 쿼리는 GitHub가 데이터 반환 전에 거부할 수 있고, 올바른 쿼리도 선택한 기간에 해당하는 활동이 없는 사용자를 반환할 수 있습니다. 진단 정보는 구체적으로 남기고 bearer token이나 Authorization 전체 헤더는 절대 로그에 기록하지 마세요.

개인정보와 기여 수치의 의미 존중

기여 달력은 프로필 활동을 보여주는 자료이지 비공개 저장소 목록이나 한 사람의 작업 전체 기록이 아닙니다. GitHub 개인정보 설정에 따라 보이는 활동이 달라질 수 있으며, 권한이 있는 앱도 사용 사례에 필요한 접근만 요청해야 합니다. 다른 사람에게 차트를 보여줄 때는 출처와 조회 기간을 설명하세요.

토큰은 자격 증명으로 다루세요. 서버의 secret 저장소나 로컬 환경 변수에서 불러오고, 가능하면 접근을 제한하며, 노출된 자격 증명을 교체하고 로그에서 지웁니다. 공개 브라우저 페이지가 서버 접근을 위해 backend를 호출해야 할 실제 이유가 있을 때만 그렇게 하며 개인용 access token을 HTML이나 JavaScript에 넣지 마세요.

기여 수를 코드 품질이나 완전한 생산성 점수처럼 제시하지 마세요. 합계에는 검토의 깊이, 유지보수 맥락, 표시되지 않는 비공개 활동이 담기지 않습니다. 시각화가 특정 날짜의 기여 달력 snapshot임을 표시하세요.