Ara que hem cobert totes les característiques i fluxos de treball principals de GitHub, però qualsevol grup gran o projecte tindrà personalitzacions que podrien voler fer o serveis externs que podrien voler integrar.
Afortunadament per a nosaltres, GitHub és realment bastant hackeable de moltes maneres. En aquesta secció cobrirem com utilitzar el sistema de hooks de GitHub i la seva API per fer que GitHub funcioni com volem.
La secció de Hooks i Serveis de l’administració del repositori de GitHub és la manera més fàcil de fer que GitHub interactuï amb sistemes externs.
Primer mirem els Serveis. Tant les integracions de Hooks com de Serveis es poden trobar a la secció de Configuració del vostre repositori, on anteriorment vam veure com afegir Col·laboradors i canviar la branca per defecte del vostre projecte. Sota la pestanya “Webhooks and Services” veureu alguna cosa com Secció de configuració de Serveis i Hooks.
Hi ha desenes de serveis entre els quals podeu triar, la majoria d’ells són integracions amb altres sistemes comercials i de codi obert. La majoria d’ells són per a serveis d’Integració Contínua, seguidors de bugs i issues, sistemes de xat i sistemes de documentació. Passarem per la configuració d’un molt senzill, el hook d’Email. Si trieu “email” del menú desplegable “Add Service”, obtindreu una pantalla de configuració com Configuració del servei d’Email.
En aquest cas, si fem clic al botó “Add service”, l’adreça de correu electrònic que hem especificat rebran un correu electrònic cada vegada que algú faci push al repositori. Els serveis poden escoltar molts tipus diferents d’esdeveniments, però la majoria només escolten esdeveniments de push i després fan alguna cosa amb aquestes dades.
Si hi ha un sistema que esteu utilitzant que voleu integrar amb GitHub, hauríeu de comprovar aquí per veure si hi ha una integració de servei existent disponible. Per exemple, si esteu utilitzant Jenkins per executar proves al vostre codi, podeu habilitar la integració de servei incorporada de Jenkins per iniciar una execució de prova cada vegada que algú faci push al vostre repositori.
Si necessiteu alguna cosa més específica o voleu integrar amb un servei o lloc que no està inclòs en aquesta llista, podeu utilitzar en lloc d’això el sistema de hooks més genèric. Els hooks del repositori de GitHub són bastant senzills. Especifiqueu una URL i GitHub farà un POST HTTP a aquesta URL en qualsevol esdeveniment que vulgueu.
Generalment, la manera com això funciona és que podeu configurar un petit servei web per escoltar una càrrega útil de hook de GitHub i després fer alguna cosa amb les dades quan es reben.
Per habilitar un hook, feu clic al botó “Add webhook” a Secció de configuració de Serveis i Hooks. Això us portarà a una pàgina que sembla Configuració del web hook.
La configuració d’un web hook és bastant senzilla.
En la majoria de casos simplement introduïu una URL i una clau secreta i feu clic a “Add webhook”.
Hi ha algunes opcions per als esdeveniments pels quals voleu que GitHub us enviï una càrrega útil — per defecte és només obtenir una càrrega útil per a l’esdeveniment push, quan algú puja nou codi a qualsevol branca del vostre repositori.
Mirem un petit exemple d’un servei web que podríeu configurar per gestionar un web hook. Utilitzarem el marc web Ruby Sinatra ja que és bastant concís i hauríeu de poder veure fàcilment el que estem fent.
Diguem que volem rebre un correu electrònic si una persona específica fa push a una branca específica del nostre projecte modificant un fitxer específic. Podríem fer això bastant fàcilment amb codi com aquest:
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
endAquí estem prenent la càrrega útil JSON que GitHub ens lliura i busquem qui l’ha pujat, a quina branca han pujat i quins fitxers van ser tocats en tots els commits que van ser pujats. Llavors ho comprovem amb els nostres criteris i enviem un correu electrònic si coincideix.
Per desenvolupar i provar alguna cosa com això, teniu una bona consola de desenvolupament a la mateixa pantalla on configureu el hook. Podeu veure els últims intents de lliurament que GitHub ha intentat fer per a aquell webhook. Per a cada hook podeu aprofundir en quan es va lliurar, si va tenir èxit i el cos i els encapçalaments tant per a la sol·licitud com per a la resposta. Això fa que sigui increïblement fàcil provar i depurar els vostres hooks.
L’altra gran característica d’això és que podeu tornar a lliurar qualsevol de les càrregues útils per provar fàcilment el vostre servei.
Per a més informació sobre com escriure webhooks i tots els diferents tipus d’esdeveniments als quals podeu escoltar, aneu a la documentació de desenvolupament de GitHub a https://docs.github.com/en/webhooks-and-events/webhooks/about-webhooks.
Els serveis i hooks us donen una manera de rebre notificacions de push sobre esdeveniments que passen als vostres repositoris, però què passa si necessiteu més informació sobre aquests esdeveniments? Què passa si necessiteu automatitzar alguna cosa com afegir col·laboradors o etiquetar issues?
Això és on l’API de GitHub és útil. GitHub té molts punts finals d’API per fer gairebé qualsevol cosa que podeu fer al lloc web de manera automatitzada. En aquesta secció aprendrem com autenticar i connectar a l’API, com comentar en un issue i com canviar l’estat d’una Pull Request a través de l’API.
La cosa més bàsica que podeu fer és una sol·licitud GET simple en un punt final que no requereix autenticació. Això podria ser un usuari o informació de només lectura en un projecte de codi obert. Per exemple, si volem saber més sobre un usuari anomenat “schacon”, podem executar alguna cosa com això:
\$ 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"
}Hi ha molts punts finals com aquest per obtenir informació sobre organitzacions, projectes, issues, commits — gairebé qualsevol cosa que podeu veure públicament a GitHub.
Fins i tot podeu utilitzar l’API per renderitzar Markdown arbitrari o trobar una plantilla de .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*
"
}No obstant això, si voleu fer una acció al lloc web com comentar en un Issue o Pull Request o si voleu veure o interactuar amb contingut privat, haurà d’autenticar-se.
Hi ha diverses maneres d’autenticar-se. Podeu utilitzar autenticació bàsica només amb el vostre nom d’usuari i contrasenya, però generalment és una millor idea utilitzar un token d’accés personal. Podeu generar això des de la pestanya “Applications” de la vostra pàgina de configuració.
Us demanarà quins àmbits voleu per a aquest token i una descripció. Assegureu-vos d’utilitzar una bona descripció perquè us sentiu còmodes eliminant el token quan el vostre script o aplicació ja no s’utilitzi.
GitHub només us mostrarà el token una vegada, així que assegureu-vos de copiar-lo. Ara podeu utilitzar això per autenticar-vos al vostre script en lloc d’utilitzar un nom d’usuari i contrasenya. Això és bo perquè podeu limitar l’àmbit del que voleu fer i el token és revocable.
Això també té l’avantatge afegit d’augmentar el vostre límit de velocitat. Sense autenticar, esteu limitat a 60 sol·licituds per hora. Si us autentiqueu podeu fer fins a 5.000 sol·licituds per hora.
Així que utilitzeu-ho per fer un comentari en un dels nostres issues.
Diguem que volem deixar un comentari en un issue específic, Issue #6.
Per fer-ho hem de fer una sol·licitud HTTP POST a repos/<usuari>/<repo>/issues/<num>/comments amb el token que acabem de generar com a capçalera d’Autorització.
\$ 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:"
}Ara si aneu a aquell issue, podeu veure el comentari que acabem de publicar com a Un comentari publicat des de l’API de GitHub.
Podeu utilitzar l’API per fer gairebé qualsevol cosa que podeu fer al lloc web — crear i establir fites, assignar persones a Issues i Pull Requests, crear i canviar etiquetes, accedir a dades de commit, crear nous commits i branques, obrir, tancar o fusionar Pull Requests, crear i editar equips, comentar línies de codi en una Pull Request, cercar al lloc i així successivament.
Hi ha un últim exemple que mirem ja que és realment útil si esteu treballant amb Pull Requests. Cada commit pot tenir un o més estats associats i hi ha una API per afegir i consultar aquest estat.
La majoria dels serveis d’Integració Contínua i proves utilitzen aquesta API per reaccionar a les pushes provant el codi que va ser pujat, i després informar si aquell commit ha passat totes les proves. També podeu utilitzar això per comprovar si el missatge del commit està correctament formatat, si el presentador va seguir totes les vostres directrius de contribució, si el commit va ser signat vàlidament — qualsevol nombre de coses.
Diguem que configureu un webhook al vostre repositori que colpeja un petit servei web que comprova una cadena Signed-off-by al missatge del commit.
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
endEspera que això sigui bastant senzill de seguir.
En aquest gestor de web hook mirem a través de cada commit que acabem de pujar, busquem la cadena 'Signed-off-by' al missatge del commit i finalment fem un POST via HTTP al punt final de l’API /repos/<usuari>/<repo>/statuses/<commit_sha> amb l’estat.
En aquest cas podeu enviar un estat ('success', 'failure', 'error'), una descripció del que va passar, una URL objectiu a la qual l’usuari pot anar per a més informació i un “context” en cas que hi hagi múltiples estats per a un sol commit. Per exemple, un servei de proves podria proporcionar un estat i un servei de validació com aquest també podria proporcionar un estat — el camp “context” és com es diferencien.
Si algú obre una nova Pull Request a GitHub i aquest hook està configurat, podríeu veure alguna cosa com Estat del commit via l’API.
Ara podeu veure una petita marca de verificació verda al costat del commit que té una cadena “Signed-off-by” al missatge i una creu vermella a través de l’altre on l’autor va oblidar de signar. També podeu veure que la Pull Request pren l’estat de l’últim commit a la branca i us avisa si és un error. Això és realment útil si esteu utilitzant aquesta API per a resultats de proves perquè no fusioneu accidentalment alguna cosa on l’últim commit està fallant les proves.
Tot i que hem estat fent gairebé tot a través de curl i sol·licituds HTTP simples en aquests exemples, existeixen diverses llibreries de codi obert que fan que aquesta API estigui disponible d’una manera més idiomàtica.
En el moment d’escriure això, els llenguatges suportats inclouen Go, Objective-C, Ruby i .NET.
Consulteu https://github.com/octokit per a més informació sobre aquests, ja que gestionen molta de la HTTP per a vosaltres.
Espera que aquestes eines us puguin ajudar a personalitzar i modificar GitHub per treballar millor per als vostres fluxos de treball específics. Per a la documentació completa sobre tota l’API així com guies per a tasques comunes, consulteu https://docs.github.com/.