Nu har vi gått igenom alla viktiga funktioner och arbetsflöden i GitHub, men varje större grupp eller projekt vill ofta göra anpassningar eller integrera externa tjänster.
Lyckligtvis är GitHub ganska enkelt att anpassa på många sätt. I det här avsnittet går vi igenom hur du använder GitHubs krok-system och dess API för att få GitHub att fungera som du vill.
Avsnittet Krokar och Tjänster i GitHubs kodförrådsadministration är det enklaste sättet att få GitHub att interagera med externa system.
Först tittar vi på tjänster. Både krokar och tjänsteintegrationer finns i inställningsdelen för ditt kodförråd, där vi tidigare tittade på att lägga till medarbetare och ändra standardgren. Under fliken "Webbkrokar och tjänster" ser du något i stil med Konfiguration av tjänster och krokar.
Det finns dussintals tjänster att välja mellan, de flesta är integrationer med andra kommersiella system och system med öppen källkod. De flesta är till för tjänster för kontinuerlig integrering, fel- och ärendehanterare, chattrumssystem och dokumentationssystem. Vi går igenom en väldigt enkel: e-postkroken. Om du väljer e-post i rullgardinen för att lägga till en tjänst får du en konfigurationsskärm som Konfiguration av e-posttjänst.
I det här fallet, om vi trycker på knappen "Lägg till tjänst" får den e-postadress vi angav ett e-postmeddelande varje gång någon skickar upp till kodförrådet. Tjänster kan lyssna på många olika typer av händelser, men de flesta lyssnar bara på skicka-händelser och gör sedan något med den datan.
Om du använder ett system som du vill integrera med GitHub bör du titta här för att se om det finns en befintlig tjänsteintegration. Om du till exempel använder Jenkins för att köra tester på din kodbas kan du aktivera Jenkins inbyggda tjänsteintegration för att starta en testkörning varje gång någon skickar upp till ditt kodförråd.
Om du behöver något mer specifikt eller vill integrera med en tjänst eller webbplats som inte finns i listan kan du i stället använda det mer generella krok-systemet. GitHubs kodförrådskrokar är ganska enkla. Du anger en URL och GitHub skickar en HTTP-last till den URL:en för vilken händelse du vill.
Vanligtvis fungerar det så att du sätter upp en liten webbtjänst som lyssnar efter en GitHub-kroks last och sedan gör något med datan när den tas emot.
För att aktivera en krok klickar du på knappen "Lägg till webbkrok" i Konfiguration av tjänster och krokar. Det tar dig till en sida som ser ut som Konfiguration av webbkrok.
Konfigurationen för en webbkrok är ganska enkel.
I de flesta fall anger du bara en URL och en hemlig nyckel och trycker på "Lägg till webbkrok".
Det finns några val för vilka händelser du vill att GitHub ska skicka en last för — standard är att bara få en last för push-händelsen, när någon skickar upp ny kod till valfri gren i kodförrådet.
Låt oss se ett litet exempel på en webbtjänst som du kan sätta upp för att hantera en webbkrok. Vi använder Ruby-ramverket Sinatra eftersom det är ganska kortfattat och det bör vara enkelt att se vad vi gör.
Säg att vi vill få ett e-postmeddelande om en specifik person skickar upp till en specifik gren i vårt projekt och ändrar en specifik fil. Det kan vi ganska enkelt göra med kod som denna:
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
endHär tar vi JSON-lasten som GitHub levererar, letar upp vem som skickade upp, vilken gren de skickade till och vilka filer som rördes i alla incheckningar som skickades upp. Sedan kontrollerar vi det mot våra kriterier och skickar ett e-postmeddelande om det matchar.
För att utveckla och testa något sånt här har du en trevlig utvecklarkonsol på samma skärm där du satte upp kroken. Du kan se de senaste leveranserna som GitHub försökt göra för den webbkroken. För varje krok kan du gräva ned i när den levererades, om den lyckades samt body och headers för både begäran och svaret. Det gör det otroligt lätt att testa och felsöka dina krokar.
En annan bra funktion är att du kan skicka om valfri last för att testa din tjänst enkelt.
För mer information om hur du skriver webbkrokar och alla olika händelsetyper du kan lyssna på, se GitHubs utvecklardokumentation på https://docs.github.com/en/webhooks-and-events/webhooks/about-webhooks.
Tjänster och krokar ger dig ett sätt att få skicka-aviseringar om händelser som sker i dina kodförråd, men vad händer om du behöver mer information om dessa händelser? Vad händer om du behöver automatisera något som att lägga till medarbetare eller märka ärenden?
Det är här GitHub-API:t kommer till nytta. GitHub har massor av API-ändpunkter för att göra nästan allt du kan göra på webbplatsen på ett automatiserat sätt. I det här avsnittet lär vi oss hur vi autentiserar och ansluter till API:t, hur vi kommenterar ett ärende och hur vi ändrar status för en ändringsförfrågan via API:t.
Det mest grundläggande du kan göra är en enkel GET-begäran mot en ändpunkt som inte kräver autentisering. Det kan vara användar- eller skrivskyddad information om ett projekt med öppen källkod. Om vi till exempel vill veta mer om en användare som heter "schacon" kan vi köra något i stil med detta:
$ 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"
}Det finns massor av API-ändpunkter som den här för att hämta information om organisationer, projekt, ärenden och incheckningar — i princip allt du kan se offentligt på GitHub.
Du kan till och med använda API:t för att rendera godtycklig Markdown eller hitta en .gitignore-mall.
$ 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*
"
}Om du däremot vill göra något på webbplatsen, som att kommentera ett ärende eller en ändringsförfrågan, eller om du vill se eller interagera med privat innehåll, behöver du autentisera dig.
Det finns flera sätt att autentisera. Du kan använda grundläggande autentisering med bara användarnamn och lösenord, men i allmänhet är det en bättre idé att använda en personlig åtkomsttoken. Du kan skapa den från fliken "Applications" på din inställningssida.
Den kommer att fråga vilka behörigheter du vill ge tokenen och en beskrivning. Se till att använda en bra beskrivning så att du känner dig trygg med att ta bort token när ditt skript eller program inte längre används.
GitHub visar tokenen bara en gång, så se till att kopiera den. Nu kan du använda den för att autentisera i ditt skript i stället för användarnamn och lösenord. Det är bra eftersom du kan begränsa vad tokenen får göra och återkalla den vid behov.
Detta har också fördelen att öka din gräns för förfrågningar. Utan autentisering är du begränsad till 60 förfrågningar per timme. Om du autentiserar dig kan du göra upp till 5 000 förfrågningar per timme.
Låt oss använda den för att lämna en kommentar i ett av våra ärenden.
Säg att vi vill lämna en kommentar i ärende #6.
För att göra det måste vi göra en HTTP POST-begäran till repos/<användare>/<kodförråd>/issues/<num>/comments med tokenen vi just skapade som en Authorization-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:"
}Om du nu går till ärendet kan du se kommentaren som vi nyss postade, som i En kommentar postad via GitHub-API:t.
Du kan använda API:t till nästan allt du kan göra på webbplatsen — skapa och sätta milstolpar, tilldela personer till ärenden och ändringsförfrågningar, skapa och ändra etiketter, komma åt incheckningsdata, skapa nya incheckningar och grenar, öppna, stänga eller sammanfoga ändringsförfrågningar, skapa och redigera team, kommentera kodrader i en ändringsförfrågan, söka på webbplatsen och så vidare.
Det finns ett sista exempel vi tittar på eftersom det är väldigt användbart om du arbetar med ändringsförfrågningar. Varje incheckning kan ha en eller flera statusar kopplade till sig och det finns ett API för att lägga till och fråga efter den statusen.
De flesta tjänster för kontinuerlig integrering och testning använder detta API för att reagera på uppskickningar genom att testa koden som skickades upp och sedan rapportera tillbaka om incheckningen klarade alla tester. Du kan också använda detta för att kontrollera om incheckningsmeddelandet är korrekt formaterat, om insändaren följde dina bidragsriktlinjer, om incheckningen var korrekt signerad — hur många saker som helst.
Säg att du har satt upp en webbkrok i ditt kodförråd som anropar en liten webbtjänst som letar efter strängen Signed-off-by i incheckningsmeddelandet.
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
endFörhoppningsvis är detta ganska enkelt att följa.
I denna webbkrokshanterare går vi igenom varje incheckning som just skickades upp, letar efter strängen "Signed-off-by" i incheckningsmeddelandet och gör sedan en HTTP POST till API-ändpunkten /repos/<användare>/<kodförråd>/statuses/<commit_sha> med statusen.
I det här fallet kan du skicka ett tillstånd ("success", "failure", "error"), en beskrivning av vad som hände, en mål-URL som användaren kan gå till för mer information och en "context" om det finns flera statusar för en och samma incheckning. Till exempel kan en testtjänst ge en status och en valideringstjänst som denna kan också ge en status — fältet "context" är hur de skiljs åt.
Om någon öppnar en ny ändringsförfrågan på GitHub och denna krok är konfigurerad kan du se något som Incheckningsstatus via API:t.
Nu kan du se en liten grön bock bredvid incheckningen som har en "Signed-off-by"-sträng i meddelandet och ett rött kryss vid den där författaren glömde signera. Du kan också se att ändringsförfrågan tar statusen från den senaste incheckningen i grenen och varnar om den är misslyckad. Det här är väldigt användbart om du använder API:t för testresultat så att du inte råkar sammanfoga något där den senaste incheckningen fallerar tester.
Även om vi har gjort nästan allt via curl och enkla HTTP-begäran i dessa exempel finns det flera bibliotek med öppen källkod som gör API:t tillgängligt på ett mer idiomatiskt sätt.
När detta skrevs fanns stöd för språk som Go, Objective-C, Ruby och .NET.
Se https://github.com/octokit för mer information om dessa, eftersom de hanterar mycket av HTTP åt dig.
Förhoppningsvis hjälper dessa verktyg dig att anpassa och ändra GitHub så att det fungerar bättre för dina specifika arbetsflöden. För fullständig dokumentation av hela API:t samt guider för vanliga uppgifter, se https://docs.github.com/.