GitHub GraphQL API: calendário de contribuições

O que a GitHub GraphQL Contributions API retorna

A GitHub GraphQL Contributions API lê o calendário de um perfil como dados estruturados de datas e contagens. Informe o login, solicite contributionsCollection para um período e selecione contributionCalendar. A resposta traz o total e semanas com dias individuais.

Cada registro diário inclui date e contributionCount. color e weekday ajudam a reproduzir o calendário; totalContributions agrega o período. Esses valores descrevem atividade do perfil, não commits de um repositório, um histórico completo ou toda atividade privada.

A referência do GitHub informa que contribuições de repositórios privados e internos só são incluídas com o escopo opcional read:user. Solicite esse acesso apenas quando o produto realmente precisar dele; caso contrário, mantenha as permissões do token mais restritas.

A solicitação é um POST GraphQL ao endpoint do GitHub e exige autenticação. Mantenha o token no servidor ou em uma variável local, limite o acesso e nunca o inclua em JavaScript, repositórios públicos ou consultas compartilhadas.

Montar uma solicitação à GitHub GraphQL Contributions API

O endpoint GraphQL do GitHub é https://api.github.com/graphql. Envie um POST com token bearer em Authorization e corpo JSON com query e variables. Separá-los facilita revisar e reutilizar a chamada com outro usuário ou período.

O exemplo consulta o calendário do perfil, não commits do repositório. Solicita total, semanas e dias de contribuição. Se precisar apenas do total anual, peça totalContributions e omita os campos aninhados.

GraphQL retorna um envelope JSON. Verifique o status HTTP e o array errors: dados e erros podem aparecer juntos. Registre separadamente a mensagem e o caminho do campo afetado.

Consulta e variáveis

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"
}

Coloque a consulta e o objeto variables no corpo JSON do POST. Mantenha um token real fora deste exemplo e confira o esquema oficial antes de adicionar outros campos.

Ler os campos do calendário de contribuições

O caminho da resposta é data.user.contributionsCollection.contributionCalendar. Trate cada nível como opcional no código: o usuário pode não ser encontrado, um campo pode estar indisponível para a conta autenticada ou a resposta pode conter erros. Verifique a resposta antes de acessar propriedades aninhadas.

totalContributions agrega o período. weeks agrupa o calendário e cada contributionDays representa uma data. contributionCount é a atividade diária; date é a data; weekday indica o dia da semana (1 é segunda-feira); color é hexadecimal, com tons escuros para mais contribuições. Guarde data e contagem como dados, e color como metadado visual.

Use os registros diários para criar uma tabela, mapa de calor ou gráfico. Preserve os dias com contagem zero; removê-los pode deslocar as datas e representar a atividade de forma incorreta.

Escolher um intervalo de datas explícito

Passe from e to como DateTime ISO 8601. Limites UTC explícitos tornam relatórios reproduzíveis e evitam diferenças de um dia entre fusos. Decida se usará a data do calendário do GitHub ou um fuso local antes de converter horários.

Em relatórios móveis, salve os limites exatos. Compare períodos de igual duração e divida históricos longos em intervalos limitados; uma resposta não é um arquivo ilimitado.

Teste limites próximos da meia-noite UTC e um período sem atividade visível. O total e os dias devem corresponder à janela pedida. Um total zero é válido e não indica falha.

Normalizar a resposta antes de criar o gráfico

Um modelo compacto permite usar a resposta em gráficos, CSV ou snapshots agendados. Achate as semanas em uma lista ordenada, mantenha data e contagem e guarde color ou weekday só se a tela precisar. Ordene por data, não pelas chaves do objeto.

Valide datas interpretáveis e contagens finitas e não negativas. Defina como tratar usuário ausente, coleção vazia, datas duplicadas, dados parciais e limite de taxa. Mostre um estado vazio claro em vez de um calendário quebrado ou zeros inventados.

O calendário do perfil responde a uma pergunta diferente do histórico de um repositório. Consulte o guia de regras do gráfico de contribuições para quadrados ausentes ou o guia do histórico de commits quando precisar de registros de um repositório.

Achatar semanas em registros diários

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));

Valide o calendário antes desta etapa e trate dados ausentes explicitamente. Preserve dias com contagem zero para manter a linha do tempo alinhada.

• Guia das regras do gráfico de contribuições do GitHub — Consulte-o para regras de contagem do perfil e quadrados ausentes.
• Guia do histórico de commits do GitHub — Consulte-o para commits, histórico de arquivos e intervalos de repositório.
• Experimentar o GitHub City — Explore o padrão público de contribuições como visualização 3D depois de conferir o gráfico de origem.

Solucionar respostas e limites do GraphQL

Em caso de falha, verifique juntos o status HTTP, o JSON e errors. O GitHub pode rejeitar uma consulta inválida ou retornar usuário sem atividade no período. Seja específico e nunca registre o token bearer nem o cabeçalho Authorization.

Respeitar a privacidade e o significado das contribuições

O calendário mostra atividade do perfil, não repositórios privados nem todo o trabalho de alguém. As configurações do GitHub afetam o que fica visível; o aplicativo deve pedir apenas o necessário. Ao compartilhar um gráfico, indique fonte e período.

Trate o token como credencial: carregue-o de um segredo do servidor ou variável local, limite permissões, troque credenciais expostas e remova-as dos registros. Nunca inclua um token pessoal em HTML ou JavaScript público.

Não use contagens como nota de qualidade ou produtividade: elas não mostram revisões, manutenção nem atividade privada. Identifique a visualização como snapshot datado do calendário.