Git
Chapters ▾ 2nd Edition

6.5 GitHub - Pag-iiskrip sa GitHub

Pag-iiskrip sa GitHub

At ngayong natalakay na natin ang lahat ng mga pangunahing tampok at workflow ng GitHub, ngunit anumang malaking grupo o proyekto ay magkakaroon ng mga pasadya na gusto nila na gawin o mga serbisyo na panlabas na gusto nilang isama.

Sa kabutihang-palad para sa atin, ang GitHub ay talagang lubos na maaaring i-hack sa maraming paraan. Sa seksyong ito, tatalakayon natin kung paano gamitin ang sistema ng mga hook ng GitHub at ang API nito upang gawin ang GitHub na gumana ayon sa gusto natin.

Mga Serbisyo at mga Hook

Ang seksyon ng mga Hook at mga Serbisyo ng pag-aadministrabo sa repositoryo ng GitHub ay ang pinakamadaling paraan upang makipag-ugnay ang GitHub sa mga panlabas na sistema.

Mga Serbisyo

Una nating tingnan ang mga Serbisyo. Ang parehong mga pagsasama ng mga Hook at Serbisyo ay matatagpuan sa seksyon ng mga Setting ng iyong repositoryo, kung saan dati nating natingnan sa pagdaragdag ng mga Tagatulong at pagbabago ng default na branch ng iyong proyekto. Sa ilalim ng tab na “Mga Webhook at mga Serbisyo” makikita natin ang isang bagay tulad ng Seksyon ng pagsasaayos sa mga Serbisyo at mga Hook..

Mga serbisyo at mga hook
Figure 130. Seksyon ng pagsasaayos sa mga Serbisyo at mga Hook.

Mayroong dose-dosenang mga serbisyo ang maaari mong pagpipilian, karamihan sa mga ito ay mga pagsasama sa iba pang mga komersyal at mga sistema na open source. Karamihan sa kanila ay para sa mga serbisyo ng Patuloy na Pagsasama, bug, at mga tracker ng isyu, mga sistema ng chat room at mga sistema ng dokumentasyon. Tatalakayin natin ang pag-set up ng isang napaka-simple, ang hook ng Email. Kung pipiliin mo ang “email” mula sa dropdown na “Magdagdag ng Serbisyo”, makakakuha ng isang screen ng pagsasaayos tulad ng Pagsasaayos ng serbisyo ng Email..

Serbisyo ng email
Figure 131. Pagsasaayos ng serbisyo ng Email.

Sa kasong ito, kung pinindot natin ang pindutan na “Magdagdag ng serbisyo”, ang tinukoy natin na email address ay makakakuha ng isang email sa tuwing may isang tao ang nag-push sa repositoryo. Ang mga serbisyo ay maaaring makinig para sa maraming iba’t-ibang uri ng mga kaganapan, ngunit karamihan lamang ay makinig para sa mga push na mga kaganapan at pagkatapos ay gawin ang isang bagay sa datos na iyon.

Kung mayroong isang sistema na iyong ginagamit na nais mong isama sa GitHub, dapat mong suriin dito upang makita kung mayroong umiiral na magagamit na pagsasama ng serbisyo. Halimbawa, kung gumagamit ka ng Jenkins upang magpatakbo ng mga pagsusuri sa iyong codebase, maaari mong paganahin ang pagsasama ng Jenkins builtin na serbisyo upang mag-umpisa ng isang patakbuhing pagsusuri sa tuwing may isang taong nag-push sa iyong repositoryo.

Mga Hook

Kung kailangan mo ng isang bagay na mas tiyak o nais mong isama sa isang serbisyo o site na hindi nabibilang sa listahang ito, maaari mong gamitin sa halip ang mas panlahat na sistema ng mga hook. Ang mga hook sa repositoryo ng GitHub ay simple lamang. Magtukoy ka ng isang URL at ipapaskil ng GitHub ang isang payload na HTTP sa URL na iyon sa anumang kaganapan na nais mo.

Sa pangkalahatan, ang paraan ng paggana nito ay maaari mong i-setup ang isang maliit na serbisyo sa web upang makinig para sa isang payload sa hook ng GitHub at pagkatapos ay gawin ang isang bagay sa datos kapag ito ay natanggap.

Upang magpagana ng isang hook, i-click ang pindutan na “Magdagdag ng webhook” sa Seksyon ng pagsasaayos sa mga Serbisyo at mga Hook.. Ito ay magdadala sa iyo sa isang pahina na katulad ng Pagsasaayos sa hook ng web..

Hook ng web
Figure 132. Pagsasaayos sa hook ng web.

Ang pagsasaayos para sa isang hook ng web ay simple lamang. Karamihan sa mga kaso, ipasok mo lamang ang isang URL at isang sekretong key at pindutin ang “Magdagdag ng webhook”. May ilang mga opsyon para sa kung aling mga kaganapan ang gusto mong saan ipadala sa iyo ng GitHub ang isang kargamento - ang default ay upang makakuha lamang ng isang kargamento para sa push na kaganapan, kapag ang isang tao ay nag-push ng bagong code sa anumang branch ng iyong repositoryo.

Tingnan natin ang isang maliit na halimbawa ng isang serbisyo sa web na maaari mong i-set up upang mahawakan ang isang hook ng web. Gagamitin natin ang balangkas na Sinatra ng web na Ruby dahil ito ay medyo maigsi at dapat mong madaling makita kung ano ang ginagawa natin.

Sabihin nating nais nating makakuha ng isang email kung ang isang partikular na tao ay nag-push sa isang partikular na branch ng ating proyekto na nagbabago sa isang partikular na file. Maaari nating madaling gawin ito na may code tulad nito:

require 'sinatra'
require 'json'
require 'mail'

post '/payload' do
  push = JSON.parse(request.body.read) # i-parse ang JSON

  # tipunin ang datos na ating hinahanap
  pusher = push["pusher"]["name"]
  branch = push["ref"]

  # kumuha ng isang listahan ng lahat ng mga file na hinawakan
  files = push["commits"].map do |commit|
    commit['added'] + commit['modified'] + commit['removed']
  end
  files = files.flatten.uniq

  # suriin para sa ating pamantayan
  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

Dito, kinukuha natin ang kargamento ng JSON na inilulunsad ng GitHub sa atin at hinahanap kung sino ang nag-push nito, kung anong branch sila nag-push at kung anu-ano ang mga file sa lahat ng mga gawaing na-push. Pagkatapos ay sinusuri natin laban sa pamantayan at nagpadala ng isang email kung ito ay tumutugma.

Upang bumuo at suriin ang isang bagay tulad nito, mayroon kang isang magaling na developer console sa parehong screen kung saan mo isi-net up ang hook. Maaari mong makita ang huling mga paghahatid na sinubukan ng GitHub upang gawin para sa webhook na iyon. Sa bawat hook maaari kang maghukay pababa kapag ito ay naihatid, kung ito ay matagumpay at ang nilalaman at mga header para sa parehong kahilingan at tugon. Ginagawa nito maging hindi kapani-paniwalang madali na suriin at i-debug ang iyong mga hook.

Pag-debug ng Webhook
Figure 133. Impormasyon sa pag-debug ng Web hook.

Ang iba pang mahusay na tampok nito ay na maaari mong maibalik ang anumang mga kargamento upang madaling masubukan ang iyong serbisyo.

Para sa karagdagang impormasyon kung paano magsulat ng mga webhook at lahat ng iba’t-ibang mga uri ng kaganapan na maaari mong pakinggan, pumunta sa dokumentasyon ng GitHub Developer sa https://developer.github.com/webhooks/

Ang API ng GitHub

Ang mga serbisyo at mga hook ay nagbibigay sa iyo ng isang paraan upang makatanggap ng mga abiso na push tungkol sa mga kaganapan na nangyayari sa iyong mga repositoryo, ngunit paano kung kailangan mo ng karagdagang impormasyon tungkol sa mga kaganapang ito? Paano kung kailangan mong gawing awtomatiko ang isang bagay tulad ng pagdaragdag ng mga tagatulong o mga isyu sa pag-label?

Ito ay kung saan ang API ng GitHub ay madaling gamitin. Ang GitHub ay may toneladang mga endpoint ng API para sa paggawa ng halos anumang bagay na maaari mong gawin sa website sa isang awtomatiko na paraan. Sa seksyong ito, matututo tayo kung paano magpatunay at kumonekta sa API, paano magkomento sa isang isyu at paano baguhin ang katayuan ng isang Kahilingan na Pull sa pamamagitan ng API.

Pangunahing Paggamit

Ang pinaka-pangunahing bagay na maaari mong gawin ay isang simpleng kahilingan na GET sa isang endpoint na hindi nangangailangan ng pagpapatunay. Ito ay maaaring isang gumagamit o impormasyon sa pagbasa lamang sa isang proyekto na open source. Halimbawa, kung gusto nating malaman ang higit pa tungkol sa isang gumagamit na pinangalanang “schacon”, maaari nating patakbuhin ang isang bagay tulad nito:

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

Mayroong toneladang mga endpoint tulad nito upang kumuha ng impormasyon tungkol sa mga organisasyon, mga proyekto, mga isyu, mga commit — halos anumang bagay na maaari mong makita nang publiko sa GitHub. Maaari mo ring gamitin ang API upang magbigay ng arbitraryo na Markdown o makahanap ng template na .gitignore.

$ curl https://api.github.com/gitignore/templates/Java
{
  "name": "Java",
  "source": "*.class

# Kasangkapan sa Mobile para sa Java (J2ME)
.mtj.tmp/

# Mga File ng Package #
*.jar
*.war
*.ear

# mga log ng pag-crash ng virtual machine, tingnan sa http://www.java.com/en/download/help/error_hotspot.xml
hs_err_pid*
"
}

Pagkokomento sa isang Isyu

Gayunpaman, kung nais mong gumawa ng isang aksyon sa website tulad ng komento sa isang Isyu o Kahilingan na Pull o kung nais mong tingnan o makipag-ugnayan sa pribadong nilalaman, kakailanganin mong magpatunay.

Mayroong maraming mga paraan upang magpatunay. Maaari mong gamitin ang pangunahing pagpapatunay gamit lamang ang iyong username at password, ngunit sa pangkalahatan mas magaling na ideya na gumamit ng isang access token na personal. Maaari mong mabuo ito mula sa tab na “Mga Aplikasyon” sa pahina ng iyong mga setting.

Access Token
Figure 134. Buuin ang iyong access token mula sa tab na “Mga Aplikasyon” sa pahina ng iyong settings.

Magtatanong ito sa iyo kung anong mga saklaw ang gusto mo para sa token na ito at isang paglalarawan. Siguraduhin na gumamit ng isang mahusay na paglalarawan upang komportable ka sa pagtatanggal ng token kapag ang iyong iskrip o aplikasyon ay hindi na nagamit.

Ipapakita lamang sa iyo ng GitHub ang token ng isang beses, kaya siguraduhin na kopyahin ito. Maaari mo na ngayong gamitin ito sa pagpapatunay ng iyong iskrip sa halip na gagamit ng isang username at password. Ito ay maganda dahil maaari mong limitahan ang saklaw kung ano ang gusto mong gawin at ang token ay mababawi.

Ito rin ay may dagdag na kalamangan ng pagtaas ng iyong limitasyon sa rate. Kung walang pagpapatunay, limitado ka sa 60 na kahilingan sa bawat oras. Kung nagpapatunay ka, maaari kang gumawa ng hanggang 5,0000 na mga kahilingan sa bawat oras.

Kaya gamitin natin ito upang gumawa ng isang komento sa isa sa ating mga isyu. Sabihin natin na nais nating mag-iwan ng isang komento sa isang partikular na isyu, Isyu #6. Para gawin ito kailangan nating gumawa ng isang kahilingan na HTTP POST sa repos/<user>/<repo>/issues/<num>/comments gamit ang token na binuo natin bilang isang header ng Pagpapatunay.

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

Ngayon kung pupunta ka sa isyung iyon, makikita mo ang komento na matagumpay nating naipaskil tulad sa Isang komentong naipaskil mula sa API ng GitHub..

Komento sa API
Figure 135. Isang komentong naipaskil mula sa API ng GitHub.

Maaari mong gamitin ang API upang gawin ang tungkol sa anumang bagay na maaari mong gawin sa website — paglilikha at pagtatakda ng mga milyahe, pagtatalaga ng mga tao sa mga Isyu at mga Kahilingan na Pull, paglilikha at pagbabago ng mga label, pag-access sa datos ng commit, paglilikha ng mga bagong commit at mga branch, pagbubukas, pagsasara o pagsasama ng mga Kahilingan na Pull, paglilikha at pag-edit ng mga koponan, pagkokomento sa mga linya ng code sa isang Kahilingan na Pull, paghahanap sa site at iba pa.

Pagbabago sa Katayuan ng isang Kahilingan na Pull

May isang pangwakas na halimbawang titingnan natin dahil talagang kapaki-pakinabang ito kung nagtatrabaho ka sa mga Kahilingan na Pull. Bawat commit ay maaaring magkaroon ng isa o higit pang mga katayuan na nauugnay dito at may isang API na idagdag at i-query ang katayuan nito.

Karamihan sa Patuloy na Integrasyon at mga serbisyo ng pagsusuri ay gumagamit ng API na ito upang tumugon sa mga push sa pamamagitan ng pagsusuri sa code na na-push na, at pagkatapos mag-ulat pabalik kung ang commit na iyon ay nakapasa sa lahat ng mga pagsusuri. Maaari mo ring gamitin ito upang suriin kung ang mensahe ng commit ay maayos na nai-format, kung ang nagsumite ay sumunod sa lahat ng mga patnubay, kung ang commit ay balidong na-sign — anumang bilang ng mga bagay.

Sabihin nating ikaw ay nag-set up ng isang webhook sa iyong repositoryo na tumatama sa isang maliit na serbisyo ng web na nagsusuri para sa isang string na Signed-off-by sa mensahe ng commit.

require 'httparty'
require 'sinatra'
require 'json'

post '/payload' do
  push = JSON.parse(request.body.read) # i-parse ang JSON
  repo_name = push['repository']['full_name']

  # tingnan ang bawat mensahe ng commit
  push["commits"].each do |commit|

    # maghanap ng isang string na Signed-off-by
    if /Signed-off-by/.match commit['message']
      state = 'tagumpay'
      description = 'Matagumpay na na-sign off!'
    else
      state = 'kabiguan'
      description = 'Walang natagpuan na signoff.'
    end

    # magpaskil ng katayuan sa GitHub
    sha = commit["id"]
    status_url = "https://api.github.com/repos/#{repo_name}/statuses/#{sha}"

    status = {
      "katayuan"       => state,
      "paglalarawan" => description,
      "target_url"  => "http://example.com/how-to-signoff",
      "konteksto"     => "validate/signoff"
    }
    HTTParty.post(status_url,
      :body => status.to_json,
      :headers => {
        'Content-Type'  => 'application/json',
        'User-Agent'    => 'tonychacon/signoff',
        'Pagpapatunay' => "token #{ENV['TOKEN']}" }
    )
  end
end

Sana ito ay medyo simple na sundin. Sa humahawak ng web hook na ito, tinitingnan natin ang bawat commit na na-push lamang, hinahanap natin ang string na Signed-off-by sa mensahe ng commit at sa wakas tayo ay nag-POST sa pamamagitan ng HTTP sa endpoint ng API na /repos/<user>/<repo>/statuses/<commit_sha>` na may katayuan.

Sa kasong ito, maaari kang magpadala ng isang katayuan (tagumpay, kabiguan, kamalian), isang paglalarawan sa kung ano ang nangyari, isang target URL na maaari puntahan ng gumagamit para sa karagdagang impormasyon at isang “konteksto” sa kaso na mayroong maramihang katayuan para sa isang solong commit. Halimbawa, isang serbisyo ng pagsusuri ay maaaring magpahintulot ng isang katayuan at isang serbisyo ng pagpapatunay tulad ng sa ito ay maaaring magpahintulot ng isang katayuan — ang patlang ng “konteksto” ay paano sila naiiba.

Kung may nagbubukas ng isang bagong Kahilingan na Pull sa GitHub at ang hook na ito ay na-set up, maaari mong makita ang isang bagay tulad ng Katayuan ng Commit sa pamamagitan ng API..

Katayuan ng Commit
Figure 136. Katayuan ng Commit sa pamamagitan ng API.

Maaari mo na ngayong makita ang isang maliit na berdeng marka ng tsek sa tabi ng commit na may “igned-off-by” na string sa mensahe at isang pulang krus sa pamamagitan ng isa kung saan ang may-akda ay nakalimutan na mag-sign off. Maaari mo ring makita na ang Kahilingan na Pull ay kumukuha sa katayuan ng huling commit sa branch at binabalaan ka kung ito ay isang kabiguan. Ito ay talagang kapaki-pakinabang kung gumagamit ka ng API na ito para sa mga resulta ng pagsusuri upang hindi mo sinasadyang pagsamahin ang isang bagay kung saan ang huling paggawa ay hindi nakakapagpapatunay ng mga pagsusuri.

Octokit

Kahit na ginagawa natin ang halos lahat ng bagay sa pamamagitan ng curl at simpleng mga kahilingan sa HTTP sa mga halimbawang ito, maraming mga open-source library na umiiral na ginagawang magagamit ang API na ito sa mas pansalitain na paraan. Sa panahon ng pagsulat na ito, ang suportadong mga language ay kinabibilangan ng Go, Objective-C, Ruby, at .NET. Tingnan mo sa http://github.com/octokit para sa karagdagang impormasyon sa mga ito, habang pinangangasiwaan nila ang marami sa HTTP para sa iyo.

Sana ang mga kasangkapan na ito ay maaaring makatulong sa iyo na ipasadya at baguhin ang GitHub upang gumana nang mas mahusay para sa iyong partikular na mga workflow. Para sa kumpletong dokumentasyon sa buong API pati na rin ang mga gabay para sa mga karaniwang gawain, tingnan ang https://developer.github.com [].

scroll-to-top