Contributions GitHub via l’API GraphQL : consulter le calendrier

Ce que renvoie l’API GraphQL des contributions GitHub

L’API GraphQL des contributions GitHub lit le calendrier d’un profil sous forme de dates et de comptes structurés. Indiquez le login, demandez contributionsCollection pour une période, puis sélectionnez contributionCalendar. La réponse contient le total et les semaines avec leurs jours de contribution.

Chaque enregistrement quotidien contient date et contributionCount. color et weekday aident à reproduire le calendrier ; totalContributions agrège la période. Ces valeurs décrivent l’activité du profil, pas les commits d’un dépôt, un historique complet ou toute activité privée.

La documentation GitHub précise que les contributions des dépôts privés et internes ne sont incluses qu’avec l’autorisation facultative read:user. Ne la demandez que si le produit en a besoin ; sinon, limitez les permissions du jeton.

La requête est un POST GraphQL vers l’endpoint GitHub et nécessite une authentification. Gardez le jeton sur un serveur ou dans une variable locale, limitez les accès et ne l’insérez jamais dans le JavaScript, un dépôt public ou une requête partagée.

Construire une requête vers l’API GraphQL des contributions GitHub

L’endpoint GraphQL GitHub est https://api.github.com/graphql. Envoyez un POST avec un jeton bearer dans Authorization et un corps JSON contenant query et variables. Les séparer facilite la relecture et la réutilisation avec un autre utilisateur ou une autre période.

L’exemple demande le calendrier du profil, pas les commits du dépôt. Il sélectionne le total, les semaines et leurs jours de contribution. Pour un total annuel seul, demandez totalContributions et omettez les champs imbriqués.

GraphQL renvoie une enveloppe JSON. Vérifiez le statut HTTP et le tableau errors : données et erreurs peuvent coexister. Consignez séparément le message et le chemin du champ concerné.

Requête et variables

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

Placez la requête et l’objet variables dans le corps JSON du POST. N’insérez pas de vrai jeton dans cet exemple et vérifiez le schéma officiel avant d’ajouter des champs.

Lire les champs du calendrier de contributions

Le chemin de réponse est data.user.contributionsCollection.contributionCalendar. Traitez chaque niveau comme facultatif dans votre code : l’utilisateur peut ne pas être résolu, un champ peut être indisponible pour le compte authentifié ou la réponse peut contenir des erreurs. Ne lisez pas les propriétés imbriquées avant d’avoir validé la réponse.

totalContributions agrège la période. weeks regroupe le calendrier et chaque contributionDays représente une date. contributionCount est l’activité du jour ; date est la date ; weekday indique le jour (1 pour lundi) ; color est une valeur hexadécimale dont les tons foncés signalent davantage de contributions. Conservez date et compte comme données, color comme métadonnée d’affichage.

La liste quotidienne permet de créer un tableau accessible, une carte d’intensité, un résumé hebdomadaire ou un graphique. Conservez aussi les jours sans activité : supprimer les zéros peut décaler la séquence et associer l’activité à la mauvaise date.

Choisir une période explicite

Passez from et to comme valeurs DateTime ISO 8601. Des bornes UTC explicites rendent les rapports reproductibles et évitent un décalage d’un jour entre fuseaux horaires. Décidez si la date suit le calendrier GitHub ou un fuseau local avant de convertir les horodatages.

Pour une vue glissante, enregistrez les bornes exactes. Comparez des périodes de même durée et découpez les historiques longs en intervalles limités ; une réponse n’est pas une archive sans fin.

Testez des bornes proches de minuit UTC et une période sans activité visible. Le total et la liste doivent correspondre à la fenêtre demandée. Un total nul est valide et ne signale pas un échec.

Normaliser la réponse avant de la représenter

Un modèle compact facilite l’usage dans un graphique, un export CSV ou un instantané. Aplatissez les semaines en liste ordonnée, gardez date et compte, puis color ou weekday si l’affichage en a besoin. Triez par date plutôt que par clés d’objet.

Vérifiez que chaque date est interprétable et que le compte est fini et positif ou nul. Définissez le traitement des utilisateurs absents, collections vides, dates doubles, données partielles et limites de débit. Affichez un état vide plutôt qu’un calendrier cassé ou des zéros inventés.

Le calendrier de profil répond à une autre question que l’historique d’un dépôt. Consultez le guide des règles du graphique de contributions GitHub pour les cases manquantes et le guide de l’historique des commits GitHub pour les enregistrements d’un dépôt.

Aplatir les semaines en enregistrements quotidiens

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

Validez le calendrier avant cette étape et traitez explicitement les données absentes. Conservez les jours à zéro pour garder la chronologie alignée.

• Guide des règles du graphique de contributions GitHub — Présente les règles du profil et les cases manquantes.
• Guide de l’historique des commits GitHub — Traite les enregistrements, les fichiers et les plages d’un dépôt.
• Essayer GitHub City — Explorez un profil public en 3D après avoir vérifié son graphique source.

Diagnostiquer les réponses GraphQL et les limites

En cas d’échec, examinez ensemble le statut HTTP, le JSON et errors. GitHub peut refuser une requête invalide ou renvoyer un utilisateur sans activité pour la période. Gardez des diagnostics précis et ne consignez jamais le jeton bearer ni l’en-tête Authorization.

Respecter la confidentialité et le sens des contributions

Le calendrier montre l’activité du profil, pas les dépôts privés ni tout le travail d’une personne. Les réglages GitHub influencent les données visibles ; une application doit demander le minimum utile. En partageant un graphique, indiquez sa source et sa période.

Traitez le jeton comme un secret : chargez-le depuis un coffre serveur ou une variable locale, limitez ses droits, renouvelez les identifiants exposés et masquez-les dans les journaux. N’intégrez jamais un jeton personnel au HTML ou au JavaScript public.

Ne présentez pas les comptes comme une note de qualité ou de productivité : ils ne montrent ni les revues, ni la maintenance, ni l’activité privée. Indiquez qu’il s’agit d’un instantané daté du calendrier.