2nd Edition

6.5 GitHub - Die Skriptering van GitHub (Scripting GitHub)

Die Skriptering van GitHub (Scripting GitHub)

Ons het nou al die hooffunksies en werkvloeie van GitHub gedek, maar enige groot groep of projek sal pasgemaakte aanpassings (customizations) wil maak of eksterne dienste wil integreer.

Gelukkig vir ons is GitHub op baie maniere redelik kapbaar (hackable). In hierdie afdeling sal ons dek hoe om die GitHub-hakestelsel (hooks system) en die API daarvan te gebruik om GitHub te laat werk soos ons dit wil hê.

Dienste en Hake (Services and Hooks)

Die Dienste en Hake-afdeling (Hooks and Services) van GitHub-bewaarplekadministrasie is die maklikste manier om GitHub met eksterne stelsels te laat kommunikeer.

Dienste (Services)

Eerstens sal ons na Dienste kyk. Beide die Hake- en Dienste-integrasies kan gevind word in die Settings-afdeling van jou bewaarplek, waar ons vroeër gekyk het na die byvoeging van Medewerkers (Collaborators) en die verandering van die verstek-tak van jou projek. Onder die “Webhooks and Services” oortjie sal jy iets sien soos Dienste en Hake konfigurasie-afdeling.

Services and Hooks configuration section

Figure 142. Dienste en Hake konfigurasie-afdeling

Daar is dosyne dienste waaruit jy kan kies, waarvan die meeste integrasies is na ander kommersiële en oopbronstelsels. Die meeste daarvan is vir Deurlopende Integrasie-dienste (Continuous Integration services), fout- en kwessie-opspoorders (bug and issue trackers), kletskamerstelsels en dokumentasiestelsels. Ons sal stap vir stap deur die opstelling van 'n baie eenvoudige een gaan, naamlik die Email-haak. As jy “email” uit die “Add Service” aftrekkieslys kies, sal jy 'n konfigurasieskerm soos E-posdiens konfigurasie kry.

Figure 143. E-posdiens konfigurasie

In hierdie geval, as ons die “Add service” knoppie druk, sal die e-posadres wat ons gespesifiseer het 'n e-pos kry elke keer as iemand na die bewaarplek push. Dienste kan luister vir baie verskillende tipes gebeurtenisse, maar die meeste luister slegs vir push-gebeurtenisse en doen dan iets met daardie data.

As daar 'n stelsel is wat jy gebruik wat jy met GitHub wil integreer, moet jy hier kyk om te sien of daar 'n bestaande diensintegrasie beskikbaar is. Byvoorbeeld, as jy Jenkins gebruik om toetse op jou kodebasis te laat loop, kan jy die ingeboude Jenkins-diensintegrasie aktiveer om 'n toetslopie af te skop elke keer as iemand na jou bewaarplek push.

Hake (Hooks)

As jy iets meer spesifiek nodig het of jy wil integreer met 'n diens of webwerf wat nie in hierdie lys is nie, kan jy in plaas daarvan die meer generiese hakestelsel (hooks system) gebruik. GitHub-bewaarplekhake is redelik eenvoudig. Jy spesifiseer 'n URL en GitHub sal 'n HTTP-loonvrag (payload) na daardie URL stuur (post) op enige gebeurtenis wat jy wil hê.

Die manier waarop dit oor die algemeen werk, is dat jy 'n klein webdiens kan opstel om te luister vir 'n GitHub-haakloonvrag en dan iets met die data doen wanneer dit ontvang word.

Om 'n haak te aktiveer, klik jy op die “Add webhook” knoppie in Dienste en Hake konfigurasie-afdeling. Dit sal jou bring na 'n bladsy wat lyk soos Webhaak konfigurasie.

Figure 144. Webhaak konfigurasie

Die konfigurasie vir 'n webhaak is redelik eenvoudig. In die meeste gevalle voer jy eenvoudig 'n URL en 'n geheime sleutel (secret key) in en druk “Add webhook”. Daar is 'n paar opsies vir watter gebeurtenisse jy wil hê GitHub 'n loonvrag voor moet stuur — die verstelling (default) is om slegs 'n loonvrag vir die push gebeurtenis te kry, wanneer iemand nuwe kode na enige tak van jou bewaarplek push.

Kom ons kyk na 'n klein voorbeeld van 'n webdiens wat jy kan opstel om 'n webhaak te hanteer. Ons sal die Ruby-webraamwerk Sinatra gebruik aangesien dit redelik bondig is en jy maklik behoort te kan sien wat ons besig is om te doen.

Sê nou ons wil 'n e-pos kry as 'n spesifieke persoon na 'n spesifieke tak van ons projek push en 'n spesifieke lêer wysig. Ons kan dit redelik maklik doen met kode soos hierdie:

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

Hier neem ons die JSON-loonvrag wat GitHub aan ons aflewer en soek wie dit gepush het, na watter tak hulle gepush het en watter lêers geraak is in al die vasleggings wat gepush is. Dan kontroleer ons dit teen ons kriteria en stuur 'n e-pos as dit ooreenstem.

Om so iets te ontwikkel en te toets, het jy 'n oulike ontwikkelaarskonsole in dieselfde skerm waar jy die haak opgestel het. Jy kan die laaste paar aflewerings sien wat GitHub probeer maak het vir daardie webhaak. Vir elke haak kan jy in diepte kyk na wanneer dit afgelewer is, of dit suksesvol was en die liggaam en opskrifte (headers) vir beide die versoek en die reaksie. Dit maak dit ongelooflik maklik om jou hake te toets en te ontfout (debug).

Figure 145. Webhaak ontfoutingsinligting

Die ander wonderlike kenmerk hiervan is dat jy enige van die loonvragte weer kan aflewer (redeliver) om jou diens maklik te toets.

Vir meer inligting oor hoe om webhake te skryf en al die verskillende tipes gebeurtenisse waarvoor jy kan luister, gaan na die GitHub Developer dokumentasie by https://docs.github.com/en/webhooks-and-events/webhooks/about-webhooks.

Die GitHub API (The GitHub API)

Dienste en hake gee jou 'n manier om push-kennisgewings te ontvang oor gebeurtenisse wat op jou bewaarplekke plaasvind, maar wat as jy meer inligting oor hierdie gebeurtenisse nodig het? Wat as jy iets moet outomatiseer soos om medewerkers by te voeg of Issues te etiketteer?

Dit is waar die GitHub API handig te pas kom. GitHub het tonne API-eindpunte (endpoints) om byna enigiets wat jy op die webwerf kan doen, op 'n geoutomatiseerde manier te doen. In hierdie afdeling sal ons leer hoe om te verifieer (authenticate) en aan die API te koppel, hoe om kommentaar te lewer op 'n Issue en hoe om die status van 'n Pull Request deur die API te verander.

Basiese Gebruik (Basic Usage)

Die mees basiese ding wat jy kan doen, is 'n eenvoudige GET-versoek (GET request) op 'n eindpunt wat nie verifikasie vereis nie. Dit kan 'n gebruiker wees of leesalleen-inligting (read-only information) oor 'n oopbronprojek. Byvoorbeeld, as ons meer wil weet oor 'n gebruiker genaamd “schacon”, kan ons iets soos dit uitvoer:

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

Daar is tonne eindpunte soos hierdie om inligting te kry oor organisasies, projekte, issues, vasleggings — so te sê enigiets wat jy in die openbaar op GitHub kan sien. Jy kan selfs die API gebruik om willekeurige Markdown weer te gee of 'n .gitignore sjabloon te vind.

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

Kommentaar op 'n Issue (Commenting on an Issue)

As jy egter 'n aksie op die webwerf wil doen, soos om kommentaar te lewer op 'n Issue of Pull Request of as jy privaat inhoud wil sien of daarmee in wisselwerking tree, sal jy moet verifieer.

Daar is verskeie maniere om te verifieer. Jy kan basiese verifikasie (basic authentication) met net jou gebruikersnaam en wagwoord gebruik, maar oor die algemeen is dit 'n beter idee om 'n persoonlike toegangsteken (personal access token) te gebruik. Jy kan dit genereer vanaf die “Applications” oortjie van jou instellingsbladsy.

Generate your access token from the “Applications” tab of your settings page

Figure 146. Genereer jou toegangsteken vanaf die “Applications” oortjie van jou instellingsbladsy

Dit sal jou vra watter bestekke (scopes) jy vir hierdie teken wil hê en 'n beskrywing. Maak seker jy gebruik 'n goeie beskrywing sodat jy gemaklik voel om die teken te verwyder wanneer jou skrip of toepassing nie meer gebruik word nie.

GitHub sal die teken net een keer vir jou wys, so maak seker dat jy dit kopieer. Jy kan dit nou gebruik om in jou skrip te verifieer in plaas daarvan om 'n gebruikersnaam en wagwoord te gebruik. Dit is lekker omdat jy die bestek van wat jy wil doen kan beperk en die teken herroepbaar (revocable) is.

Dit het ook die bykomende voordeel dat dit jou tempobeperking (rate limit) verhoog. Sonder verifikasie sal jy beperk word tot 60 versoeke per uur. As jy verifieer, kan jy tot 5 000 versoeke per uur rig.

Kom ons gebruik dit dus om 'n opmerking op een van ons Issues te maak. Sê nou ons wil 'n opmerking los op 'n spesifieke Issue, Issue #6. Om dit te doen moet ons 'n HTTP POST-versoek aan repos/<user>/<repo>/issues/<num>/comments rig met die teken wat ons pas gegenereer het as 'n Authorization-opskrif (header).

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

Nou as jy na daardie Issue gaan, kan jy die opmerking sien wat ons pas suksesvol gepos het, soos in 'n Opmerking gepos via die GitHub API.

Figure 147. 'n Opmerking gepos via die GitHub API

Jy kan die API gebruik om net omtrent enigiets te doen wat jy op die webwerf kan doen — die skep en stel van mylpale (milestones), die toewysing van mense aan Issues en Pull Requests, die skep en verandering van etikette (labels), toegang tot vasleggingsdata (commit data), die skep van nuwe vasleggings en takke, die oopmaak, toemaak of saamsmelt van Pull Requests, die skep en redigering van spanne, kommentaar op reëls kode in 'n Pull Request, soek op die werf en so meer.

Verandering van die Status van 'n Pull Request (Changing the Status of a Pull Request)

Daar is nog een laaste voorbeeld waarna ons sal kyk, aangesien dit regtig nuttig is as jy met Pull Requests werk. Elke vaslegging kan een of meer statusse hê wat daarmee geassosieer is en daar is 'n API om daardie status by te voeg en te bevraagteken (query).

Die meeste van die Deurlopende Integrasie (Continuous Integration) en toetsdienste maak gebruik van hierdie API om op pushes te reageer deur die kode te toets wat gepush is, en dan terug te rapporteer of daardie vaslegging al die toetse geslaag het. Jy kan dit ook gebruik om te kyk of die vasleggingsboodskap behoorlik geformatteer is, of die indiener al jou bydraeriglyne gevolg het, of die vaslegging geldig geteken was — enige aantal dinge.

Kom ons sê jy stel 'n webhaak (webhook) op jou bewaarplek op wat 'n klein webdiens tref wat vir 'n Signed-off-by string in die vasleggingsboodskap soek.

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

Hopelik is dit redelik eenvoudig om te volg. In hierdie webhaak-hanteerder kyk ons deur elke vaslegging wat pas gepush is, ons soek na die string 'Signed-off-by' in die vasleggingsboodskap en uiteindelik doen ons 'n POST via HTTP na die /repos/<user>/<repo>/statuses/<commit_sha> API-eindpunt (endpoint) met die status.

In hierdie geval kan jy 'n toestand ('success', 'failure', 'error') stuur, 'n beskrywing van wat gebeur het, 'n teiken-URL waarheen die gebruiker kan gaan vir meer inligting en 'n “konteks” (context) ingeval daar veelvuldige statusse vir 'n enkele vaslegging is. Byvoorbeeld, 'n toetsdiens kan 'n status verskaf en 'n valideringsdiens soos hierdie kan ook 'n status verskaf — die “konteks” veld is hoe hulle onderskei word.

As iemand 'n nuwe Pull Request op GitHub oopmaak en hierdie haak is opgestel, sal jy dalk iets soos Vasleggingstatus via die API sien.

Figure 148. Vasleggingstatus via die API

Jy kan nou 'n klein groen regmerkie sien langs die vaslegging wat 'n “Signed-off-by” string in die boodskap het en 'n rooi kruisie deur die een waar die outeur vergeet het om af te teken. Jy kan ook sien dat die Pull Request die status aanneem van die laaste vaslegging op die tak en jou waarsku as dit 'n mislukking (failure) is. Dit is baie nuttig as jy hierdie API vir toetsresultate gebruik sodat jy nie per ongeluk iets insmelt (merge) waar die laaste vaslegging toetse dop nie.

Octokit

Alhoewel ons byna alles in hierdie voorbeelde deur curl en eenvoudige HTTP-versoeke gedoen het, bestaan daar verskeie oopbron-biblioteke (open-source libraries) wat hierdie API op 'n meer idiomatiese manier beskikbaar stel. Ten tyde van hierdie skrywe sluit die ondersteunde tale Go, Objective-C, Ruby en .NET in. Kyk na https://github.com/octokit vir meer inligting hieroor, aangesien hulle baie van die HTTP vir jou hanteer.

Hopelik kan hierdie gereedskap jou help om GitHub aan te pas en te wysig om beter vir jou spesifieke werkvloeie te werk. Vir volledige dokumentasie oor die hele API asook gidse vir algemene take, kyk na https://docs.github.com/.

prev | next

1. Aan die slag

2. Git Basics

3. Git Branching

4. Git on the Server

5. Distributed Git

6. GitHub

7. Git Tools

8. Customizing Git

9. Git and Other Systems

10. Git Internals