Git
Chapters ▾ 2nd Edition

6.5 GitHub - Skriptni GitHub

Skriptni GitHub

Torej sedaj smo pokrili vse glavne lastnosti in poteke dela GitHub-a, vendar katerakoli večja skupina ali projekt bo imela prilagoditve po meri, ki jih želijo narediti ali zunanje storitve, ki jih želijo integrirati.

Na srečo za nas je GitHub resnično precej zmožen hekanja na mnoge načine. V tej sekciji bomo pokrili, kako uporabljati GitHub sistem kljuk in njegov API, da naredimo GitHub delati, kakor želimo.

Kljuke

Administracija sekcije kljuk in storitev repozitorija GitHub je najenostavnejši način, da ima GitHub interakcijo z zunanjimi sistemi.

Storitve

Najprej bomo pogledali storitve. Obe integraciji kljuke in storitve se lahko najde v sekciji Settings vašega repozitorija, kjer smo prej pogledali dodajanje sodelavcev in spreminjanje privzete veje za vaš projekt. Pod zavihkom “Webhooks and Services” boste videli nekaj kot je Services and Hooks configuration section..

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

Na voljo je ducat storitev, ki jih lahko izberete, večina od teh integracij v ostale komercialne in odprto kodne sisteme. Večina njih je za storitve stalne integracije, sledenja hroščev in težav, sisteme pogovornih sob in sisteme dokumentaicije. Šli bomo skozi nastavitve zelo enostavne, e-poštne kljuke. Če izberete “email” iz padajočega menija “Add Service”, boste dobili nastavitveni zaslon, kot je Email service configuration..

Email service
Figure 131. Email service configuration.

V tem primeru, če pritisnemo gumb “Add service”, bo naslov e-pošte, ki smo ga določili, dobil e-pošto vsakič, ko nekdo potisne v repozitorij. Storitve lahko poslušajo za veliko različnih tipov dogodkov, vendar večinoma samo poslušajo za dogodke potiskanja in nato naredijo nekaj s temi podatki.

Če je sistem, ki ga uporabljate in ga želite integrirati z GitHub-om, bi morali tu preveriti, da vidite, če je že obstoječa integracija storitev na voljo. Na primer, če uporabljate Jenkins za poganjanje testov na vaši bazi kode, lahko omogočite Jenkins vgrajeno storitveno integracijo za začetek poganjanja testov vsakič, kot nekdo potisne v vaš repozitorij.

Kljuke

Če potrebujete narediti nekaj bolj specifičnega ali želite integrirati storitev ali stran, ki ni vključena v ta seznam, lahko namesto tega uporabite bolj generične sisteme kljuk. Kljuke repozitorija GitHub so precej enostavne. Določite URL in GitHub bo poslal HTTP naročilo na ta URL na kateremkoli dogodku želite.

V splošnem je način, kako to deluje, da lahko nastavite majhno spletno storitev in da posluša za Github kljuko nalaganja in nato naredi nekaj s podatki, ko so prejeti.

Da omogočite kljuku, kliknite na gumb “Add webhook” v Services and Hooks configuration section.. To vam bo prineslo stran, ki izgleda kot Web hook configuration..

Web hook
Figure 132. Web hook configuration.

Nastavitev za spletno kljuko je precej enostavna. V večini primerov enostavno vnesete URL in skriti ključ ter pritisnete “Add webhook”. Na voljo je nekaj opcij za katerimi dogodki želite, da vam GitHub pošlje nalaganje — privzeto je samo dobiti nalaganje za dogodek push, ko nekdo potisne novo kodo na katerokoli vejo vašega repozitorija.

Poglejmo majhen primer spletne storitve, ki jo morda želite nastaviti za upravljanje spletne kljuke. Uporabili bomo Ruby spletno ogrodje Sinatra, ker je precej jedrnato in vi bi morali uspeti enostavno pogledati, kaj delate.

Recimo, da želite dobiti e-pošto, če določena oseba potisne na določeno vejo vašega projekta in spremeni določeno datoteko. To bi lahko naredili precej enostavno s kodo takole:

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

Tu vzamemo JSON nalaganje, ki nam ga GitHub dostavi in pogledamo, kdo ga je potisnil, na katero vejo je potisnil in katere datoteke so bile dotaknjene v vseh pošiljanjih, ki so bila potisnjena. Nato to pregledamo napram našim kriterijem in pošljemo e-pošto, če se ujema.

Da razvijemo in pretestiramo nekaj takega imate lepo razvijalsko konzolo v istem zaslonu, kjer nastavite kljuko. Vidite lahko zadnjih nekaj dostav, ki jih je GitHub poskušal narediti za to spletno kljuko. Za vsako kljuko se lahko poglobite, ko je bila dostavljena, če je bila uspešna in telo ter glave za tako zahtevek in odziv. To naredi izjemno enostavno testirati in razhroščevati vaše kljuke.

Webhook debug
Figure 133. Web hook debugging information.

Za ostale odlične lastnosti tega je, da lahko ponovno dostavite katerokoli nalaganje za testiranje vaše storitve enostavno.

Za več informacij, kako ponovno pisati spletne kljuke in vse različne tipe dogodkov, ki jih lahko poslušate, pojdite na GitHub razvijalsko dokumentacijo na: https://developer.github.com/webhooks/

GitHub API

Spletne storitve in kljuke vam dajo način kako prejeti obvestila potiskanja o dogodkih, ki so se zgodili na vaših repozitorijih, vendar kaj pa če potrebujete več informacij o teh dogodkih? Kaj če potrebujete avtomatizirati nekaj kot je dodajanje sodelavcev ali označevanje težav?

To je, kjer GitHub API pride prav. GitHub ima tono API končnih točk za delati skoraj karkoli lahko naredite na spletni strani na avtomatiziran način. V tej sekciji se bomo naučili, kako overiti in se povezati na API, kako komentirati težavo in kako spremeniti status zahtevka potega preko API-ja.

Osnovna uporaba

Najosnovnejša stvar, ki jo lahko naredite je enostaven GET zahtevek na končni točki, ki ne zahteva overitvije. To je lahko uporabnik ali samo bralne informacije na odprto kodnem projektu. Na primer, če želite vedeti več o uporabniku imenovanem “shacon”, lahko poženemo nekaj kot je:

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

Na voljo je tona končnih točki kot je ta, da se dobi informacije o organizacijah, projektih, težavah, pošiljanjih — skoraj karkoli lahko javno vidite na GitHub-u. Lahko celo uporabite API za izpis arbitrarnega Markdown-a ali najdete predlogo .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*
"
}

Komentiranje na težavi

Vendar, če želite narediti akcijo na spletni strani kot je komentiranje na težavi ali zahtevku potega ali če želite pogledati ali imeti interakcjo z zasebno vsebino, boste morali narediti overitev.

Obstaja nekaj načinov za overjanje. Lahko uporabite osnovno overjanje s samo vašim uporabniškim imenom in geslom, vendar v splošnem je to slaba ideja uporabiti žeton zasebnega dostopa. To lahko generirate iz zavihka “Applications” strani vaših nastavitev.

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

Vprašalo vas bo za kakšen obseg želite ta žeton in opis. Zagotovite, da uporabljate dober opis, da se počutite udobno, ko odstranjujete žeton, ko vaša skripta ali aplikacija ni več v uporabi.

GitHub vam bo samo prikazal žeton enkrat, torej bodite prepričani, da ga kopirate. Sedaj ga lahko uporabite za overitev v vaši skripti namesto uporabe uporabniškega imena in gesla. To je lepo, ker lahko omejite obseg česar želite narediti in žeton je možno umakniti.

To ima tudi dodano prednost povečanja vaše mejne stopnje. Brez overitvije boste omejeni na 60 zahtevkov na uro. Če naredite overitev lahko naredite do 5000 zahtevkov na uro.

Torej uporabimo, da naredimo komentar na eni izmed vaših težav. Predpostavimo, da želite pustiti komentar na določeni težavi, Issue #6. Da to naredite, moramo narediti HTTP POST zahtevek na repos/<user>/<repo>/issues/<num>/comments z žetonom, ki ste ga ravnokar generirali kot glavo overitvije.

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

Sedaj če greste na to težavo, lahko vidite komentar, ki smo ga ravnokar uspešno poslali kot v A comment posted from the GitHub API..

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

Uporabite lahko API, da naredite skoraj vse, kar lahko naredite na spletni strani — ustvarjanje in nastavitev mejnikov, določanje ljudi težavam in zahtevkom potegov, ustvarjanje in spreminjanje oznak, dostopanje do podatkov pošiljanja, ustvarjanje novih pošiljanj in vej, odpiranje, zapiranje ali združevanje zahtevkov potega, ustvarjanje in urejanje ekip, komentiranje na vrsticah kode v zahtevku potega, iskanje na strani itd.

Sprememba statusa zahtevka potega

En zadnji primer, ki ga bomo pogledali, saj je resnično uporaben, če delate z zahtevki potegov. Vsako pošiljanje ima lahko en ali več statusov povezanih z njim in na voljo je API za dodajanje in poizvedbo tega statusa.

Večina storitev stalne integracije in testiranja uporabljajo ta API, da reagirajo in potiskajo testno kodo, ki je bila potiskana in nato poročajo nazaj, če je to pošiljanje šlo skozi vse teste. Lahko bi tudi uporabili to za preveriti, če je sporočilo pošiljanja ustrezno oblikovano, če je pošiljatelj sledil vsem vašim smernicam prispevanja, če je bilo pošiljanje veljavno podpisano — katerokoli število stvari.

Recimo, da ste nastavili spletno kljuko na vašem repozitoriju, ki doseže majhno spletno storitev, ki preveri za niz Signed-off-by v sporočilo pošiljanja.

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

Upajmo, da je to precej enostavno za slediti. V tej spletni kljuki hendlerja bomo pogledali vsako pošiljanje, ki je bilo samo potisnjeno, pogledamo za niz Signed-off-by v sporočilu pošiljanja in končno naredimo POST preko HTTP na /repos/<user>/<repo>/statuses/<commit_sha> končno točko API-ja s statusom.

V tem primeru lahko pošljemo status (success, failure, error), opis, kaj se je zgodilo, ciljni URL, kamor gre lahko uporabnik po več informacij in “context” v primeru, da je več statusov za eno pošiljanje. Na primer testna storitev lahko ponuja status in storitev preverjanja kot tudi ponuja status - polje “context” je v čemer se razlikujeta.

Če nekdo odpre nov zahtevek potega na GitHub-u in je ta kljuka nastavljena, lahko vidite nekaj kot je Commit status via the API..

Commit status
Figure 136. Commit status via the API.

Sedaj lahko vidite majhen zeleni izbirnik zraven pošiljanja, ki ima niz “Signed-off-by” v sporočilu in rdeči križec preko, kjer se je avtor pozabil podpisati. Vidite lahko tudi, da zahtevek potega vzame status zadnjega pošiljanja na veji in vas posvari, če gre za neuspeh. To je resnično uporabno, če uporabljate ta API za rezultate testov, da po nesreči ne združite nečesa, kjer je zadnje pošiljanje padlo na testih.

Octokit

Čeprav smo do sedaj delali skoraj vse preko curl in enostavnih HTTP zahtevkov v teh primerih, obstoja nekaj odprto-kodnih knjižnic, ki naredijo ta API na voljo na bolj idiomatski način. V času tega pisanja podprti jeziki vključujejo Go, Objective-C, Ruby in .NET. Preverite http://github.com/octokit za več informacij o tem, kako upravljajo večino HTTP-ja za vas.

Upajmo, da vam ta orodja lahko pomagajo prilagoditi in spremeniti GitHub, da dela boljše za vaš določen potek dela. Za celotno dokumentacijo o celotnem API-ju kot tudi vodičih za pogosta opravila, preverite https://developer.github.com.