Git
Chapters ▾ 2nd Edition

6.5 GitHub - Skriptni GitHub

Skriptni GitHub

Torej sedaj smo pokrili vse glavne lastnosti in poteke dela GitHuba, vendar katerakoli večja skupina ali projekt bo želela prilagoditve po meri ali integrirati zunanje storitve.

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

Storitve in kljuke

Razdelek kljuk in storitev v administraciji repozitorija GitHub je najenostavnejši način, da se pripravi GitHub na interakcijo z zunanjimi sistemi.

Storitve

Najprej bomo pogledali storitve. Obe integraciji kljuke in storitve se lahko najde v razdelku »Settings« vašega repozitorija, kjer smo prej pogledali dodajanje sodelavcev in spreminjanje privzete veje vašega projekta. Pod zavihkom »Webhooks and Services« boste videli nekaj, kot je na sliki Nastavitveni razdelek storitve in kljuke.

Nastavitveni razdelek storitve in kljuke
Slika 129. Nastavitveni razdelek storitve in kljuke

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

Nastavitve e-poštne storitve
Slika 130. Nastavitve e-poštne storitve

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

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

Kljuke

Če morate 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 na ta URL poslal koristno vsebino HTTP, za katerikoli dogodek želite.

V splošnem je način, kako to deluje, da nastavite majhno spletno storitev, ki posluša za Githubovo kljuko koristnih vsebin in nato nekaj naredi s podatki, ko jih prejme.

Da kljuko omogočite, kliknite na gumb »Add webhook« na sliki Nastavitveni razdelek storitve in kljuke. To vas bo prineslo na stran, ki izgleda kot slika Nastavitev spletne kljuke.

Nastavitev spletne kljuke
Slika 131. Nastavitev spletne kljuke

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 možnosti, za katere dogodke želite, da vam GitHub pošlje koristne vsebine — privzeto dobi samo koristne vsebine 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 Rubyjevo spletno ogrodje Sinatra, ker je precej jedrnato in lahko enostavno vidite, kaj delamo.

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

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 koristno vsebino JSON, ki nam ga dostavi GitHub in pogledamo, kdo je potisnil, na katero vejo je potisnil in katere datoteke so bile dotaknjene v vseh potrditvah, ki so bile potisnjene. Nato to pregledamo zoper svoja merila in pošljemo e-pošto, če se ujemajo.

Da nekaj takega razvijete in testirate, imate v istem zaslonu dobro razvijalsko konzolo, kjer nastavite kljuko. Vidite lahko zadnjih nekaj dostav, ki jih je GitHub poskušal narediti za to spletno kljuko. V vsako kljuko se lahko poglobite, kdaj je bila dostavljena, ali je bila uspešna in vidite telo ter glave tako za zahtevek kot za odziv. To naredi testiranje in razhroščevanje vaše kljuke izjemno enostavno.

Informacije razhroščevanja spletne kljuke
Slika 132. Informacije razhroščevanja spletne kljuke

Druga odlična lastnost tega je, da lahko ponovno dostavite katerokoli koristno vsebino za enostavno testiranje svoje storitve.

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://docs.github.com/en/webhooks-and-events/webhooks/about-webhooks.

API GitHub

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

Tu pride prav GitHubov API. GitHub ima tono končnih točk API, ki naredijo na avtomatiziran način skoraj karkoli, kar lahko naredite na spletni strani. V tem razdelku 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 zahtevek GET na končni točki, ki ne zahteva overjanja. To je lahko uporabnik ali informacija samo za branje na odprtokodnem projektu. Na primer, če želimo vedeti več o uporabniku imenovanem »schacon«, lahko poženemo nekaj takega:

$ 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 cela tona končnih točk, kakršna je ta, da se dobijo informacije o organizacijah, projektih, težavah, potrditvah — skoraj karkoli, kar lahko javno vidite na GitHubu. API lahko uporabite celo za izpis poljubnega Markdowna, ali da 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 https://www.java.com/en/download/help/error_hotspot.xml
hs_err_pid*
"
}

Komentiranje na težavi

Vendar če želite narediti dejanje na spletni strani, kot je komentiranje na težavi ali zahtevku potega, ali pa če želite pogledati ali imeti interakcijo z zasebno vsebino, boste morali narediti overjanje.

Obstaja nekaj načinov za overjanje. Lahko uporabite osnovno overjanje s samo svojim uporabniškim imenom in geslom, vendar v splošnem je boljša ideja uporabiti žeton zasebnega dostopa. Tega lahko generirate iz zavihka »Applications« na strani vaših nastavitev.

Generirajte žeton dostopa iz zavihka »Applications« vaše strani nastavitev
Slika 133. Generirajte žeton dostopa iz zavihka »Applications« vaše strani nastavitev

Vprašalo vas bo, za kakšen obseg želite ta žeton in za opis. Prepričajte se, da uporabljate dober opis, saj ga boste morali prepoznati pri odstranjevanju žetona, ko vaš skript ali aplikacija ni več v uporabi.

GitHub vam bo prikazal žeton samo enkrat, torej poskrbite, da ga kopirate. Sedaj ga lahko uporabite za overjanje v svojem skriptu namesto uporabe uporabniškega imena in gesla. To je dobro, saj lahko omejite obseg, kar želite narediti, in žeton lahko tudi umaknete.

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

Torej uporabimo ga, 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 zahtevek HTTP POST na repos/<user>/<repo>/issues/<num>/comments z žetonom, ki ste ga ravnokar generirali, kot glavo overitve.

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

Če greste sedaj na to težavo, lahko vidite komentar, ki smo ga ravnokar uspešno poslali kot na sliki Komentar poslan iz API-ja GitHub.

Komentar poslan iz API-ja GitHub
Slika 134. Komentar poslan iz API-ja GitHub

API lahko uporabite, da naredite skoraj karkoli, kar lahko naredite na spletni strani — ustvarjanje in nastavitev mejnikov, dodeljevanje ljudi težavam in zahtevkom potegov, ustvarjanje in spreminjanje oznak, dostopanje do podatkov potrditev, ustvarjanje novih potrditev 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

Tu je zadnji primer, ki ga bomo pogledali, saj je resnično uporaben, če delate z zahtevki potegov. Vsaka potrditev ima lahko eden ali več z njo povezanih statusov in na voljo je API za dodajanje in poizvedbo tega statusa.

Večina storitev stalne integracije in testiranja uporablja ta API, da reagirajo in potiskajo testno kodo, ki je bila potisnjena in nato poročajo nazaj, če je ta potrditev šla skozi vse teste. Lahko bi to tudi uporabili za preverjanje, če je sporočilo potrditve ustrezno oblikovano, če je potrditelj sledil vsem vašim smernicam prispevkov, če je bila potrditev veljavno podpisana — katerokoli število stvari.

Recimo, da ste nastavili spletno kljuko na svojem repozitoriju, ki doseže majhno spletno storitev, katera preveri za niz Signed-off-by v sporočilu potrditve.

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

Upamo, da je to precej enostavno slediti. V tem krmilniku spletne kljuke smo pogledali vsako potrditev, ki je bila ravnokar potisnjena, pogledali smo za niz Signed-off-by v sporočilu potrditve in končno naredimo POST preko HTTP na končno točko API-ja s statusom /repos/<user>/<repo>/statuses/<commit_sha>.

V tem primeru lahko pošljete stanje (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 potrditev. Na primer, testna storitev lahko ponudi status in taka storitev preverjanja lahko tudi ponudi status — razlikujeta se v polju »context«.

Če nekdo odpre nov zahtevek potega na GitHubu in je ta kljuka nastavljena, lahko vidite nekaj kot je slika Status potrditve preko API-ja.

Status potrditve preko API-ja
Slika 135. Status potrditve preko API-ja

Sedaj lahko zraven potrditve vidite majhen zeleni izbirnik, ki ima niz »Signed-off-by« v sporočilu in rdeči križec, kjer se je avtor pozabil podpisati. Vidite lahko tudi, da zahtevek potega vzame status zadnje potrditve na veji in vas posvari, ali 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 zadnja potrditev padla na testih.

Octokit

Čeprav smo do sedaj delali v teh primerih skoraj vse preko curl in enostavnih zahtevkov HTTP, obstaja kar nekaj odprtokodnih knjižnic, ki naredijo ta API na voljo na še bolj idiomatski način. V času tega pisanja podprti jeziki vključujejo Go, Objective-C, Ruby in .NET. Preverite https://github.com/octokit za več informacij o tem, saj vam upravlja večino HTTP-ja.

Upamo, da vam lahko ta orodja koristijo prilagoditi in spremeniti GitHub, da dela boljše za vaš določeni potek dela. Popolno dokumentacijo celotnega API-ja in vodnike za pogosta opravila preverite na https://docs.github.com/.

scroll-to-top