Чому парсинг GitHub дає рвані дані про криптопроєкти
Відкритий API віддає не історію розробки, а поточний зріз репозиторію: список гілок, останні коміти, стан запитів на злиття.
Авторство, дати й обсяг правок за старими змінами доводиться витягувати посторінково, і будь-який пропущений запит залишає діру в активності репозиторіїв, яку потім уже нічим закрити.
Ліміти запитів перетворюють це на гонку. Без токена з розширеною квотою та зважаючи на вторинні обмеження пошуку збір за сотнею проєктів зупиняється на середині: частина репозиторіїв отримує повний профіль, частина — лише хвіст останніх тижнів. Метрики комітів у проєктів із різною датою початку збору після цього неспівставні.
Друга проблема — топологія.
Коміт із форку, дзеркала або бота безперервної збірки у видачі виглядає так само, як робота основного розробника: rebase і squash переписують авторство, force-push прибирає гілку із загального графа, а оновлення залежностей генерує сотні службових комітів.
Поки такі події не розмічені окремо, графік активності зростає саме в той момент, коли команда лагодить збірку або переносить репозиторій.
Неповна історія в сумі зі склеюванням гілок дає цифри, за якими не можна порівнювати проєкти між собою — а саме на них найчастіше й будують оцінки. Розбираємо, як це закривається: яка схема збору дає відтворюваний профіль активності та як відокремити розробку від службового шуму.
Що дає керований збір активності репозиторіїв
Налагоджений збір відповідає на три питання: скільки історії ми бачимо, наскільки свіжі цифри й що відбувається, коли зовнішнє джерело перестає віддавати дані. Відповідь на кожне вимірюється, а не відчувається.
Повнота історії комітів і релізів
Збирач проходить не лише основну гілку, а й теги, релізні гілки, злиття, авторство й дати — картина складається з усіх значущих посилань репозиторію в GitHub. Якщо обійти лише верхівку, метрика покаже затишшя там, де насправді триває робота в гілці супроводу. На виході — набір даних, де видно і разові сплески, і рівний ритм підтримки.
Свіжість даних і затримка оновлення
Оновлення відбувається за розкладом із вікном перекриття: остання доба перезбирається, тому пізні правки та переписана історія не губляться. Затримка між подією та її появою у вітрині — години, а не тижні: відтік розробників видно до того, як про нього напишуть в оглядах.
Запас за лімітами запитів знімає головний ризик. Після вичерпання квоти збір не зупиняється, а йде з меншою частотою, черга наздоганяє пропущене без дір у рядах. Якість датасету перестає залежати від одного вдалого проходу — метрики зіставні між проєктами та в часі.
Підходи до парсингу GitHub: обхід, вебхуки, інкрементальна вибірка
Знімання даних із GitHub ведуть трьома режимами, і вони не замінюють одне одного: суцільний обхід дає повноту історії, інкрементальна вибірка — дешевизну регулярних оновлень, повідомлення про зміни — свіжість.
Вибір залежить від того, чи потрібна вся історія проєкту або лише дельта з моменту останнього збору.
| Режим збору даних | Коли підходить | Обмеження джерела даних |
|---|---|---|
| Суцільний обхід | Первинне завантаження історії, звірка пропусків після збою | Найдовший, упирається в ліміти запитів |
| Інкрементальна вибірка | Планове оновлення метрик: дельта за датами або курсором | Потрібно зберігати стан і вміти перегравати вікно |
| Повідомлення про зміни | Реакція за хвилини: коміти, релізи, задачі, коментарі | Потрібна публічна адреса, доставка подій не гарантована |
Коли який режим вигідний
Суцільний обхід запускаємо один раз під час підключення проєкту та повторюємо точково, коли в метриках видно діру. Інкрементальна вибірка стає основним режимом: вона забирає лише змінені ділянки та знімає основну частину навантаження. Повідомлення доповнюють її там, де важлива затримка, а не повнота.
Обмеження лімітів і способи їх обходу
Кількість запитів на годину обмежена, окремо спрацьовують сплескові серії звернень і ліміти на вибірку великими сторінками.
Обгортаємо це так: знижуємо частоту, кешуємо відповіді та запитуємо лише змінене, розносимо навантаження за кількома токенами, у разі відмови ставимо паузу й повторюємо — збір іде, не впираючись у стіну.
Етапи впровадження збору даних про криптопроєкти
Порядок робіт майже не залежить від конкретного проєкту: спочатку інвентаризація джерел, потім модель зберігання, далі звірка там, де активність уже відома вручну. Етапи впровадження вибудовуємо так, щоб кожен крок залишав перевірюваний артефакт — вивантаження, схему, розрахунок. Тоді розходження ловляться на початку, коли переробка займає години, а не тижні.
- Аудит джерел: які події доступні (коміти, запити на злиття, обговорення, релізи, копії репозиторіїв) і що віддає програмний інтерфейс GitHub з урахуванням лімітів на частоту звернень.
- Схема даних: сутності «проєкт», «репозиторій», «учасник», «подія», ключі та правила злиття дублікатів, єдиний час, сирі відповіді поруч із розрахунковими таблицями.
- Довідники проєктів: канонічний список із прив’язкою репозиторію, токена й команди, обробка перейменувань, перенесень коду та дзеркал, ручні правки з історією.
- Завантажувач: інкрементальний збір за курсором, повторні спроби при збоях, запис без дублів, журнал запусків із тривалістю та обсягом.
- Розрахунок метрик: активність за авторами, частка унікальних учасників, регулярність і серії комітів, вікна агрегації, окремі правила для ботів.
- Перевірка на еталонних проєктах: звіряємо з ручним підрахунком за проєктами із заздалегідь відомою активністю, розходження більше кількох відсотків розбираємо до причини.
- Передача рішення: регламент оновлення довідників, документація зі схеми даних, інструкція щодо додавання проєктів, спільний розбір із вашою командою.
Схема даних і довідники залишаються у вас: нові метрики та джерела додаються без перезбирання всього конвеєра.
Що передаємо на руки: конфігурації, схеми, регламенти
Усі артефакти передаються в репозиторій замовника разом із правами доступу — нічого не залишається на нашому боці, і супровід не залежить від нас. На момент здачі контур збору працює автономно, а його стан видно без читання коду.
Документація та регламенти оновлення
- Конфігурації збору: перелік джерел, глибина первинного завантаження, розклад запусків, правила виключення проєктів.
- Схема даних: опис таблиць, ключів і зв’язків між комітами, релізами, учасниками та тегами версій.
- Регламент оновлення: періодичність опитування, поведінка при зміні структури відповідей GitHub, порядок підключення нового проєкту.
- Документація розгортання: як підняти контур з нуля та перенести його на інші потужності без правки коду.
- Інструкція для аналітика: де лежать метрики активності та як будувати власні вибірки запитами.
Моніторинг і оповіщення
- Перевірки доступності джерел і залишку лімітів звернень — сигнал приходить до того, як вивантаження почне відставати.
- Контроль свіжості: якщо останній запис старіший за очікуване вікно, спрацьовує повідомлення.
- Панель стану збору: скільки проєктів оброблено за прогін, де були відмови, як змінювався обсяг даних.
- Журнал помилок із контекстом запиту, щоб причину збою можна було знайти без звернення до нас.
Базові сценарії — перезапуск прогону, додавання проєкту, розбір збою — замовник закриває сам. Решту бере на себе команда супроводу.
Кейс: як зросла повнота даних за того самого обсягу запитів
Клієнт — платформа аналітики криптопроєктів: інвестори дивляться на активність команд у репозиторіях і за нею ухвалюють рішення.
Дані збирали регулярним парсингом GitHub, але зріз покривав лише 61% потрібних організацій — частина проєктів виглядала «мертвою» при живих комітах, і аналітики правили звіти руками.
Що було до
Обхід ішов за плоским довідником репозиторіїв: лише основна гілка, без форків і дзеркал, без урахування переїздів команди до нової організації.
При спрацюванні обмежень на частоту звернень задача падала цілком, наступний прохід стартував лише на інший день — в історії з’являлися пропуски по 2-3 доби, а агрегати за період рахувалися за датою останнього коміту замість суми за днями. Частка відмов запитів трималася на рівні 4,2%, і кожну відмову доводилося добирати вручну.
Що стало після
Збір перебудували на обхід за організаціями з посторінковою видачею та збереженням курсора — перерваний прохід продовжується з того самого місця, а не з початку.
Додали розбір розгалуження та форків, проміжне сховище метаданих, щоб не звертатися до джерела двічі за одним і тим самим, і повтор запитів із наростаючою паузою.
Повнота покриття зросла з 61% до 94%, частка відмов упала до 0,3%, а кількість звернень до джерела — той самий обсяг запитів — збільшилася лише на 8%.
Повний перезбір історії скоротився з 6 годин до 40 хвилин, і в аналітичному зведенні більше немає проєктів із нульовою активністю при живих комітах.
Чим відрізняється збір через API від розбору сторінок проєкту?
Програмний інтерфейс GitHub віддає дані в структурованому вигляді: схема полів задокументована, відповідь надходить у машинозчитуваному форматі, а ліміти запитів відомі заздалегідь.
Для регулярного збору метрик це дає передбачуване навантаження та низьку вартість підтримки — конектор пишеться один раз і живе, поки проєкт сам не змінить схему або правила доступу.
Розбір сторінок працює там, де програмного інтерфейсу немає або він віддає не все: графік внеску, список учасників, помісячна історія активності.
Підхід гнучкіший, але тримається на верстці чужого сайту — будь-яка зміна на боці проєкту ламає розбір мовчки, віддаючи нулі замість помилки.
Тому таке джерело потребує постійного нагляду: еталонні сторінки під тестами, звірка контрольних значень, оповіщення при падінні кількості подій.
Головний критерій вибору — не швидкість першого вивантаження, а надійність джерела та стійкість до змін на боці проєкту.
| Джерело | Коли підходить | Обмеження |
|---|---|---|
| Програмний інтерфейс | Штатні метрики: коміти, релізи, учасники, залежності | Жорсткі ліміти запитів, частина полів закрита |
| Вебхуки | Потрібні події в момент появи, без затримки опитування | Потребують публічної адреси та захисту від повторів |
| Розбір сторінок | Агрегати й зрізи, яких немає в інтерфейсі | Ламається при зміні верстки, потрібен моніторинг |
Ми беремо інтерфейс за основу, а розбір сторінок — як додатковий шар із перевіркою збіжності: якщо значення розходяться, падає оповіщення, і метрика не йде у звіт. Опишіть, які показники проєкту потрібні на виході, — повернемося з оцінкою обсягу джерел і планом збору.
Технічні сумніви: ліміти, дублікати, історичні дані
Історію активності проєкту піднімаємо й заднім числом: публічний програмний інтерфейс віддає посторінкові зрізи комітів, злиттів і учасників, добові зрізи та архіви закривають провали там, де видача впирається в обмеження глибини.
Збір упирається не в доступ, а в частоту запитів і сміття в даних: без розподілу за вікном і кешування повторів нічний прогін губиться цілком. Нижче — заперечення, які надходять до старту.
Відновите історію за минулі періоди?
Так, але з різною точністю. Чим глибший період, тим вищий шанс, що видача не віддасть дані — добираємо добовими зрізами та архівами, тому на старих ділянках метрика достовірна на рівні тижнів, а не годин.
Як рахуєте внесок, якщо коміт потрапив у кілька гілок?
Ключ — хеш зміни плюс батьківський коміт: злиття, повторні зрізи та перенесення між гілками згортаються, гілка не вважається окремим внеском. Інакше активність завищується в рази й рейтинг проєкту спотворюється.
Що робити із закритими репозиторіями?
Публічно вони недоступні, тому у звіт ідуть непрямі ознаки — теги релізів і активність у пов’язаних відкритих дзеркалах. Частка закритої роботи позначається як невідома, а не як нуль: інакше живий проєкт виглядає замороженим.
Боти й дзеркала не спотворюють картину?
Спотворюють, якщо їх не відокремлювати. Автоматичні коміти та дзеркала фільтруємо за автором, регулярністю й типом змін, список ведемо окремо та показуємо в розрізі за репозиторієм.
Обговоримо вашу задачу зі збору даних про проєкти
Щоб повернутися з оцінкою та планом робіт, нам потрібен від вас мінімум вхідних даних — зазвичай розбираємо їх на першій розмові. Чим конкретніший список проєктів і питань до даних, тим точніша оцінка трудовитрат і строків: не доведеться закладати запас на невизначеність.
- Перелік проєктів і репозиторіїв: організації, дзеркала та форки, які потрібно враховувати або навпаки виключати.
- Джерела даних: публічний GitHub через API, дзеркала на інших майданчиках, ваші внутрішні таблиці та вивантаження.
- Набір метрик: частота комітів, кількість активних контриб’юторів, злиття, закриті задачі, релізи, швидкість реакції на звернення.
- Глибина історії та період: з якої дати збирати, потрібне разове вивантаження чи регулярне оновлення за розкладом.
- Формат видачі: таблиці, база даних, передача у вашу систему, готові зведення й графіки для звітів.
- Вимоги до якості: як відсікати ботів і накручування активності, що робити з перейменованими та заархівованими репозиторіями.
- Доступи й обмеження: токени з потрібними правами, ліміти звернень до джерел, допустиме навантаження на ваші сервіси.
- Правила зберігання й оновлення зібраних даних, відповідальний за приймання результату на вашому боці.
Після цього повертаємося з оцінкою строків, планом робіт за етапами та описом того, що отримаєте на виході. Якщо частина вхідних даних ще не готова — обговоримо, які уточнення критичні, а які можна зняти по ходу проєкту.
