Git
Chapters ▾ 2nd Edition

6.6 GitHub - Скриптирање на GitHub

Скриптирање на GitHub

Значи сега ги опфаќаме сите главни карактеристики и работни текови на GitHub, но секоја голема група или проект ќе има прилагодувања што можеби ќе сакаат да ги направат или надворешни услуги што можеби ќе сакаат да ги интегрираат.

За среќа, за нас, GitHub е навистина прифатлив на многу начини. Во овој дел ќе покриеме како да го користиме системот GitHub и неговите API за да го направат GitHub да работи како сакаме.

Услуги и Куки

Одделот за куки и услуги на администрацијата на складиштето GitHub е најлесниот начин да се комуницира GitHub со надворешни системи.

Услуги

Прво ќе ги разгледаме Услугите. И интеграциите на "Куки" и "Услуги" може да се најдат во делот за поставувања на вашето складиште, каде што претходно размислувавме да додаваме соработници и да ја смениме стандардната гранка на вашиот проект. Под табот "Веб-книги и услуги" ќе видите нешто како << _ services_hooks >>.

Services and hooks
Figure 125. Services and Hooks configuration section.

Постојат десетици услуги од кои можете да изберете, од кои повеќето се интегрира во други комерцијални и софтвер со отворен код. Повеќето од нив се за услугите за континуирана интеграција, бубачки и издавачи, системи за разговор и системи за документација. Ние ќе одиме преку поставување на многу едноставна, е-пошта кука. Ако изберете "email" од паѓачкото мени "Add Service", ќе добиете конфигурациски екран како << _ service_config >>.

Email service
Figure 126. Email service configuration.

Во овој случај, ако го достигнеме копчето "Додај услуга", адресата на е-поштата што ја наведовме ќе добие е-пошта секој пат кога некој ќе турка до складиштето. Услугите можат да слушаат многу различни типови на настани, но повеќето само слушаат за притисни настани, а потоа прават нешто со тие податоци.

Ако постои систем кој го користите што би сакале да се интегрирате со GitHub, треба да проверите тука за да видите дали постои достапна интеграција на сервисите. На пример, ако користите Jenkins да извршувате тестови на вашата codebase, можете да ја овозможите Jenkins вградената интеграција на сервиси за да започнете тест пробни секој пат кога некој ќе турка до вашето складиште.

Куки

Ако ви треба нешто поспецифично или сакате да се интегрирате со некоја услуга или сайт кој не е вклучен во оваа листа, наместо тоа, можете да го користите системот со повеќе генерички куки. Куките за складирање на GitHub се прилично едноставни. Вие наведете URL и GitHub ќе објави HTTP носивост на таа УРЛ на кој било настан што го сакате.

Генерално, начинот на кој работи е, можете да поставите мала веб-услуга за да слушате GitHub товар и потоа да направите нешто со податоците кога ќе се примат.

За да овозможите кука, кликнете на копчето ‘Додај webhook '’ во << _ services_hooks >>. Ова ќе ве однесе на страница што изгледа како << _ web_hook >>.

Web hook
Figure 127. Web hook configuration.

Конфигурацијата за веб-кука е прилично едноставна. Во повеќето случаи, едноставно внесете URL и таен клуч и кликнете "Додај webhook". Постојат неколку опции за кои настани сакате GitHub да ви испрати товар - стандардно е да се добие само товар за настанот, кога некој турка нов код во која било гранка на вашето складиште.

Ајде да видиме мал пример на веб-сервис што може да го поставите за да се справи со веб-јамка. Ќе ја користиме рубинската веб-структура Синатра, бидејќи е прилично концизна и треба лесно да видите што правиме.

Да речеме дека сакаме да добиеме е-пошта ако одредена личност турка до одредена гранка на нашиот проект, модифицирајќи ја специфичната датотека. Ние можеме прилично лесно да го сториме тоа со код вака:

require 'sinatra'
require 'json'
require 'mail'

post '/payload' do
  push = JSON.parse(request.body.read) # parse the JSON

  # gather the data we're looking for
  pusher = push["pusher"]["name"]
  branch = push["ref"]

  # get a list of all the files touched
  files = push["commits"].map do |commit|
    commit['added'] + commit['modified'] + commit['removed']
  end
  files = files.flatten.uniq

  # check for our criteria
  if pusher == 'schacon' &&
     branch == 'ref/heads/special-branch' &&
     files.include?('special-file.txt')

    Mail.deliver do
      from     'tchacon@example.com'
      to       'tchacon@example.com'
      subject  'Scott Changed the File'
      body     "ALARM"
    end
  end
end

Овде земаме JSON корист што GitHub нè испорачува и гледа во тоа кој го турна, на која гранка се туркаа и кои датотеки беа допрени во сите извршени задачи. Потоа го проверуваме тоа според нашите критериуми и испраќаме е-пошта ако се совпаѓа.

Со цел да се развие и тестира нешто слично, имате убава конзола за програмери на истиот екран каде што ќе ја поставите куката. Можете да ги видите последните неколку испораки што GitHub се обиде да ги направи за тој webhook. За секоја кука можете да ископате кога ќе се испорача, ако е успешна и телото и заглавјата за барањето и за одговорот. Ова го прави неверојатно лесен за тестирање и дебагирање на вашите куки.

Webhook debug
Figure 128. Web hook debugging information.

Другата одлична карактеристика на ова е што можете да го вратите било кој товар за лесно тестирање на вашата услуга.

За повеќе информации за тоа како да напишете webhooks и сите различни типови на настани што можете да ги слушате, одете до документацијата за програмери GitHub на https://developer.github.com/webhooks/

GitHub API

Услугите и куките ви даваат начин да добивате известувања за настаните што се случуваат во вашите складишта, но што ако ви требаат повеќе информации за овие настани? Што ако треба да автоматизирате нешто како додавање на соработници или проблеми со етикетирање?

Ова е местото каде што GitHub API е во корист. GitHub има тони API крајни точки за правење речиси нешто што можете да го направите на веб-сајтот на автоматизиран начин. Во овој дел ќе научиме како да се идентификуваме и да се поврземе со API, како да коментираме за некое прашање и како да го смените статусот на барање за повлекување преку API.

Основна употреба

Најосновното нешто што можете да го направите е едноставно барање за ГЕТ на крајната точка која не бара автентикација. Ова може да биде корисник или само за читање информации за проект со отворен код. На пример, ако сакаме да дознаеме повеќе за корисник наречен ‘` schacon '’, можеме да работиме вака:

$ curl https://api.github.com/users/schacon
{
  "login": "schacon",
  "id": 70,
  "avatar_url": "https://avatars.githubusercontent.com/u/70",
# …
  "name": "Scott Chacon",
  "company": "GitHub",
  "following": 19,
  "created_at": "2008-01-27T17:19:28Z",
  "updated_at": "2014-06-10T02:37:23Z"
}

Постојат тони на крајните точки како што е ова за да добиете информации за организации, проекти, прашања, обврски - само за нешто што јавно може да го видите на GitHub. Можете дури да го користите API за да направите произволен Markdown или да пронајдете шаблон .gitignore.

$ curl https://api.github.com/gitignore/templates/Java
{
  "name": "Java",
  "source": "*.class

# Mobile Tools for Java (J2ME)
.mtj.tmp/

# Package Files #
*.jar
*.war
*.ear

# virtual machine crash logs, see http://www.java.com/en/download/help/error_hotspot.xml
hs_err_pid*
"
}

Коментирајќи за проблемот

Меѓутоа, ако сакате да направите некоја акција на веб-страница како што е коментар за прашање или барање за повлекување, или ако сакате да гледате или да комуницирате со приватна содржина, ќе треба да се идентификувате.

Постојат неколку начини за автентикација. Можете да ја користите основната автентикација само со вашето корисничко име и лозинка, но генерално е подобра идеја да користите личен пристапен знак. Можете да генерирате ова од табулаторот "Апликации" на вашата страница за поставки.

Access Token
Figure 129. Generate your access token from the “Applications” tab of your settings page.

Тоа ќе ве праша за кои области сакате за овој знак и опис. Осигурајте се дека користите добар опис, за да се чувствувате удобно да го отстраните токенот кога вашата скрипта или апликација веќе не се користи.

GitHub само ќе ви го прикаже токен еднаш, па не заборавајте да го копирате. Сега можете да го користите ова за да се идентификувате во вашата скрипта, наместо да користите корисничко име и лозинка. Ова е убаво затоа што можете да го ограничите опсегот на она што сакате да го направите и токен да се отповика.

Ова, исто така, има додадена предност за зголемување на вашата стапка. Без проверка на автентичност, ќе бидете ограничени на 60 барања на час. Ако се идентификувате, можете да направите до 5.000 барања на час.

Значи, да го искористиме за да дадеме коментар за едно од нашите проблеми. Да речеме дека сакаме да оставиме коментар за одредено прашање, број 6. За да го сториме тоа, ние треба да направиме HTTP POST барање до `repos / <user> / <repo> / issues / <num> / comments" со токенот кој штотуку го генериравме како заглавие за авторизација.

$ curl -H "Content-Type: application/json" \
       -H "Authorization: token TOKEN" \
       --data '{"body":"A new comment, :+1:"}' \
       https://api.github.com/repos/schacon/blink/issues/6/comments
{
  "id": 58322100,
  "html_url": "https://github.com/schacon/blink/issues/6#issuecomment-58322100",
  ...
  "user": {
    "login": "tonychacon",
    "id": 7874698,
    "avatar_url": "https://avatars.githubusercontent.com/u/7874698?v=2",
    "type": "User",
  },
  "created_at": "2014-10-08T07:48:19Z",
  "updated_at": "2014-10-08T07:48:19Z",
  "body": "A new comment, :+1:"
}

Сега, ако одите во тоа прашање, можете да го видите коментарот што ние едноставно успешно го објавивме како во << _ api_comment >>.

API Comment
Figure 130. A comment posted from the GitHub API.

Можете да го користите API за да направите само нешто што можете да го направите на веб-страницата - креирање и поставување на пресвртници, доделување на луѓе на Issues and Pull Requests, креирање и менување етикети, пристап до податоци за извршување, создавање на нови обврски и филијали, отворање, затворање или спојување на барањата за влечење, креирање и уредување тимови, коментирање на линиите на код во барање за повлекување, пребарување на страницата и на и натаму.

Промена на статусот на барањето за потпишување

Постои еден последен пример што ќе го разгледаме, бидејќи тоа е навистина корисно ако работите со Потребно за повлекување. Секоја посветеност може да има еден или повеќе статуси поврзани со него и има API за да го додаде и побара тој статус.

Повеќето од услугите за континуирана интеграција и тестирање го користат овој API за да реагираат на туркање со тестирање на кодот кој бил турнат, а потоа да се пријави ако таа обврска ги поминала сите тестови. Исто така, можете да го користите ова за да проверите дали пораката за извршување е правилно форматирана, ако подносителот ги следеше сите упатства за придонес, ако извршувањето беше валидно потпишано - било кој број работи.

Да речеме дека поставувате webhook на вашето складиште кое удира на мала веб-услуга која проверува за низа од "потпишана-надвор" во пораката за извршување.

require 'httparty'
require 'sinatra'
require 'json'

post '/payload' do
  push = JSON.parse(request.body.read) # parse the JSON
  repo_name = push['repository']['full_name']

  # look through each commit message
  push["commits"].each do |commit|

    # look for a Signed-off-by string
    if /Signed-off-by/.match commit['message']
      state = 'success'
      description = 'Successfully signed off!'
    else
      state = 'failure'
      description = 'No signoff found.'
    end

    # post status to GitHub
    sha = commit["id"]
    status_url = "https://api.github.com/repos/#{repo_name}/statuses/#{sha}"

    status = {
      "state"       => state,
      "description" => description,
      "target_url"  => "http://example.com/how-to-signoff",
      "context"     => "validate/signoff"
    }
    HTTParty.post(status_url,
      :body => status.to_json,
      :headers => {
        'Content-Type'  => 'application/json',
        'User-Agent'    => 'tonychacon/signoff',
        'Authorization' => "token #{ENV['TOKEN']}" }
    )
  end
end

Се надевам дека ова е прилично едноставно да се следи. Во овој управувач за веб-јамка гледаме низ секој извршен настан кој штотуку го туркавме, бараме низа "Signed-off-by" во пораката за извршување и конечно ќе поставиме преку HTTP на `/ repos / <user> / <repo> / statuses / <commit_sha> `крајната точка на API со статус.

Во овој случај, можете да испратите држава (успех, неуспех, грешка), опис на она што се случило, целна адреса за која корисникот може да оди за повеќе информации и ‘` контекст ’ во случај да постојат повеќе статуси за една посветеност. На пример, сервисот за тестирање може да обезбеди статус и службата за валидација како оваа, исто така, може да обезбеди статус - полето `` context ' е како тие се диференцирани.

Ако некој отвори ново барање за повлекување на GitHub и оваа кука е поставена, може да видите нешто како << commit_status >>.

Commit status
Figure 131. Commit status via the API.

Сега можете да видите малку зелена ознака за обележување до извршувањето кое има порака ‘` Отпишано-оф-по '’ во пораката и црвен крст преку оној во кој авторот заборавил да се потпише. Исто така можете да видите дека барањето за повлекување го зема статусот на последното извршување на филијалата и ве предупредува дали е неуспех. Ова е навистина корисно ако го користите овој API за резултатите од тестот, па не случајно може да се спојат нешто каде што последната заложба е неуспешни тестови.

Octokit

Иако во овие примери практикуваме скоро сè преку curl и едноставни HTTP-барања, постојат неколку библиотеки со отворен код кои го прават овој API достапен на поизразено начин. Во времето на ова пишување, поддржаните јазици вклучуваат Go, Objective-C, Ruby и .NET. Проверете http://github.com/octokit [] за повеќе информации за овие, бидејќи тие се справи со голем дел од HTTP за вас.

Се надевам дека овие алатки може да ви помогнат да го прилагодите и менувате GitHub за да работат подобро за вашите конкретни работни процеси. За комплетна документација за целиот API, како и водичи за вообичаени задачи, проверете https://developer.github.com [].

scroll-to-top