Jinsi ya Kuweka GitHub Actions Runner kwenye VPS

Kile ambacho GitHub Actions runner inayojisimamia hufanya

GitHub Actions runner inayojisimamia ni programu unayoweka kwenye VPS yako mwenyewe. Huomba kazi kutoka GitHub na kuziendesha kwenye maunzi yako. Unaisajili kwa hazina moja, unaisakinisha kama huduma ya systemd, na huanza tena baada ya kila kuwasha upya. GitHub hupanga kazi. Seva yako hufanya kazi hiyo.

CI (continuous integration) kwenye mashine unayomiliki ina manufaa kwa sababu mbili. Dakika za ujenzi hazipimwi tena, na kazi inaweza kufikia vitu vinavyopatikana kwenye mashine yako pekee, kama akiba ya ujenzi iliyo tayari au mtandao wa faragha. Gharama yake ni usalama. Runner hutekeleza chochote kinachoelezwa na faili ya workflow, kwa kutumia mtumiaji uliyempa. Kwa hiyo, faili ya workflow ni utekelezaji wa msimbo wa mbali kwa muundo wake. Kwenye hazina ya faragha, hilo ni salama kwa sababu watu unaowaamini pekee ndio wanaoweza kuongeza faili hiyo. Kwenye hazina ya umma, ni hatari halisi, na sehemu kuhusu maombi ya pull kutoka fork inaeleza utaratibu huo.

Kila kitu hapa chini kinatumia Ubuntu 24.04 pamoja na runner version 2.336.0, ambayo ni toleo la sasa kufikia Julai 2026.

Unachohitaji kabla ya kuanza

Anza na VPS iliyo na akaunti ya kawaida ya msimamizi na sudo, katika hali unayofikia baada ya dakika kumi za kwanza kwenye VPS mpya. Huhitaji kufungua mlango wa kuingiza miunganisho. Runner hufungua muunganisho wa HTTPS (itifaki salama ya uhamishaji wa maandishi) wa kutoka kwenda GitHub na kuudumisha ukiwa wazi inaposubiri kazi. Kwa hiyo, GitHub haiunganishi kamwe na seva yako. Firewall yako inaweza kubaki imefungwa kwa ulimwengu wa nje, na kazi bado zitafika.

Pia unahitaji haki za msimamizi kwenye repository, kwa sababu tokeni ya usajili huonyeshwa katika mipangilio ya repository.

Unda mtumiaji maalumu wa runner

Usiwahi kuendesha runner kama root au kama mtumiaji wako wa usimamizi. Kila job hurithi ruhusa za mtumiaji wa runner, kwa hiyo workflow inayotumia sudo hufaulu ikiwa mtumiaji wa runner anaweza kutumia sudo. Unda mtumiaji asiye na privilijia ambaye anamiliki tu saraka yake ya nyumbani. Akaunti za watumiaji zenye ruhusa chache kwenye VPS inaeleza muundo wa jumla. Huu hapa ni usanidi mahususi.

sudo useradd -m -s /bin/bash gharunner
sudo passwd -l gharunner
sudo chmod 750 /home/gharunner
sudo install -d -m 700 -o gharunner -g gharunner /home/gharunner/actions-runner

passwd -l hufunga nenosiri, kwa hiyo hakuna mtu anayeweza kuingia kama gharunner kwa kulitumia. Mode 700 kwenye saraka ya runner ni muhimu kwa sababu runner huhifadhi vitambulisho vyake humo katika maandishi wazi, na checkout inaweza kuwa na msimbo wa chanzo wa siri.

Kagua sifa zote mbili kabla ya kuendelea:

sudo passwd -S gharunner
sudo -l -U gharunner

passwd -S huchapisha mstari unaoanza na gharunner L, ambapo L inamaanisha kuwa nenosiri limefungwa. sudo -l -U gharunner inapaswa kutoa jibu la is not allowed to run sudo. Ikiwa inachapisha orodha ya amri zinazoruhusiwa badala yake, akaunti iko katika kundi la sudo, na utengaji uliouunda umeondoka.

Pakua runner na ukague tarball

Kuanzia hapa, fanya kazi kama mtumiaji wa runner.

sudo -iu gharunner
cd ~/actions-runner
RUNNER_VERSION=2.336.0
curl -fL -o actions-runner-linux-x64-${RUNNER_VERSION}.tar.gz \
  "https://github.com/actions/runner/releases/download/v${RUNNER_VERSION}/actions-runner-linux-x64-${RUNNER_VERSION}.tar.gz"

Endesha uname -m kwanza ikiwa huna uhakika kuhusu usanifu. x86_64 hutumia faili ya linux-x64 iliyo hapo juu. aarch64 hutumia actions-runner-linux-arm64-${RUNNER_VERSION}.tar.gz.

Sasa thibitisha ulichopakua. SHA256 (secure hash algorithm, 256 bit) iliyo hapa chini ni ya tarball ya 2.336.0 x64. GitHub huonyesha thamani ya toleo la sasa kwenye ukurasa wa toleo na kwenye skrini ya New self-hosted runner. Thamani hiyo hubadilika kwa kila toleo, kwa hiyo inakili kutoka hapo unaposakinisha toleo tofauti.

echo "04cf0be1aff4c3ec3554466c39124ca250e3effd8873bb7e8d68535aa9505d5d  actions-runner-linux-x64-2.336.0.tar.gz" | sha256sum -c

Upakuaji sahihi huonyesha mstari mmoja:

actions-runner-linux-x64-2.336.0.tar.gz: OK

Faili iliyokatika au kubadilishwa huonyesha ujumbe wa kushindwa na onyo:

actions-runner-linux-x64-2.336.0.tar.gz: FAILED
sha256sum: WARNING: 1 computed checksum did NOT match

Usiruke ukaguzi huu na kuiacha tar itambue tatizo baadaye. Kumbukumbu iliyohifadhiwa nusu hushindwa kwa gzip: stdin: unexpected end of file na tar: Unexpected EOF in archive. Hii inaonyesha kuwa faili imeharibika, lakini haionyeshi ikiwa ilikatika kabla ya kukamilika au ilibadilishwa.

tar xzf ./actions-runner-linux-x64-2.336.0.tar.gz
ls

Kifurushi cha tarball kina nini, na hakina nini

Baada ya kukitoa, saraka ina config.sh, run.sh, env.sh, safe_sleep.sh, bin/ na externals/. bin/ ina jozi za binary za runner na bin/installdependencies.sh. externals/ ina mazingira ya Node yaliyojumuishwa ambayo vitendo vya JavaScript hutumia kutekelezwa.

Bado hakuna svc.sh. Nyaraka za GitHub zinakieleza kama hati "inayoundwa baada ya kuongeza runner kwa mafanikio", kwa sababu huandikwa kutoka kwenye kiolezo chenye jina la hazina yako na la runner yako likiwa limejumuishwa katika jina la huduma. Kwa hiyo sudo ./svc.sh install kabla ya ./config.sh hushindwa kwa sudo: ./svc.sh: command not found. Sajili kwanza, kisha sakinisha huduma.

Sakinisha vitegemezi vya runner

runner ni programu ya .NET, kwa hiyo inahitaji maktaba kadhaa zinazoshirikiwa. Acha shell ya mtumiaji wa runner kama ilivyo na usakinishe maktaba hizo kwa kutumia sudo, kwa sababu script huandika kwenye hifadhidata ya vifurushi vya mfumo.

exit
cd /home/gharunner/actions-runner
sudo ./bin/installdependencies.sh

Kwenye Ubuntu 24.04, amri hiyo hupakua libkrb5-3, zlib1g, liblttng-ust1t64, libssl3t64 na libicu74. Script hujaribu majina kadhaa ya matoleo kwa kila maktaba na huhifadhi lile linalotolewa na toleo lako. Ndiyo maana script hiyo hiyo hufanya kazi kwenye Ubuntu za zamani na Debian.

Ruka hatua hii na ./config.sh husimama kabla haijafanya chochote:

Dependencies is missing for Dotnet Core 6.0
Execute sudo ./bin/installdependencies.sh to install any missing Dotnet Core 6.0 dependencies.

libicu inayokosekana hutoa ushauri huohuo chini ya mstari wa kwanza tofauti, Libicu's dependencies is missing for Dotnet Core 6.0. Yote hayo hutokana na sehemu moja: config.sh huendesha ldd dhidi ya maktaba zilizojumuishwa kabla haijaanza, kwa hiyo kiungo kisichotatuliwa husimamisha script badala ya kusababisha hitilafu isiyoeleweka baadaye.

Sajili runner kwenye hazina yako

Pata token kutoka kwenye hazina. Fungua Settings, kisha Actions, kisha Runners, halafu New self-hosted runner. Ukurasa huo unaonyesha registration token inayoanza na A. Token hiyo inaisha muda saa moja baada ya kuundwa, kwa hiyo itengeneze ukiwa tayari kuiweka.

Jisajili kama mtumiaji wa runner. config.sh inakataa kuendeshwa chini ya sudo.

sudo -iu gharunner
cd ~/actions-runner
./config.sh --url https://github.com/YOUR-USER/YOUR-REPO \
  --token PASTE_REGISTRATION_TOKEN_HERE \
  --name vps-runner-1 \
  --labels vps \
  --work _work \
  --unattended \
  --replace

Kazi za flags hizo. --name huamua jinsi runner inavyoonekana kwenye hazina, kwa hiyo chagua jina ambalo bado utalitambua baada ya miezi sita. --labels huongeza labels zako; runner tayari ina self-hosted, Linux na X64 bila kuombwa. --work hutaja saraka ambako checkouts huwekwa, ndani ya saraka ya runner. --unattended hujibu maulizo shirikishi kwa kutumia majibu yao ya msingi, jambo linalofaa wakati command iko ndani ya script. --replace huchukua nafasi ya usajili uliopo wenye jina hilo badala ya kushindwa, jambo linalofaa unapounda upya server.

Utekelezaji uliofanikiwa huishia na mistari hii:

√ Runner successfully added
√ Runner connection is good
√ Settings Saved.

Usajili sasa umehifadhiwa katika saraka ya runner kama .runner, .credentials na .credentials_rsaparams. Hivi viwili vya mwisho humtambulisha runner huyu kwa GitHub, kwa hiyo mtu yeyote anayeweza kuvisoma anaweza kujifanya kuwa runner huyo. Ndiyo sababu saraka ina mode 700 na mtumiaji hana sudo.

Sakinisha runner kama huduma ya systemd

./run.sh kwenye terminal inafaa kwa jaribio moja, lakini huacha kufanya kazi pamoja na kipindi chako cha SSH. Sakinisha huduma ili runner ianze wakati wa kuwasha mfumo. huduma na vipima muda vya systemd kwenye VPS inaeleza faili za unit zenyewe. Hapa svc.sh inakuandalia moja.

exit
cd /home/gharunner/actions-runner
sudo ./svc.sh install gharunner
sudo ./svc.sh start
sudo ./svc.sh status

svc.sh inahitaji root kwa sababu inaandika unit kwenye /etc/systemd/system na kuiwezesha. Hoja iliyo baada ya install ni mtumiaji ambaye huduma itaendeshwa naye. Weka gharunner wazi. Bila hoja, hati hutumia $SUDO_USER, ambao ni akaunti yako ya msimamizi, kisha kila kazi huendeshwa na mtumiaji anayeweza kutumia sudo.

Unit hupewa jina kulingana na hazina na runner, kwa muundo wa actions.runner.YOUR-USER-YOUR-REPO.vps-runner-1.service. Huhitaji kamwe kuiandika mwenyewe:

systemctl list-units 'actions.runner.*'
sudo journalctl -u 'actions.runner.*' -n 20 --no-pager

Runner inayofanya kazi vizuri huandika √ Connected to GitHub kwenye logi, kisha mstari unaoishia na Listening for Jobs, na ukurasa wa Runners wa hazina huionyesha ikiwa Idle. Runner inayoonyeshwa kama Offline ama haifanyi kazi au haiwezi kufikia GitHub kwenye port 443.

Tuma kazi kwa runner

runs-on huchagua runner kwa kutumia lebo. Omba self-hosted pamoja na lebo yako mwenyewe, ili kazi isiwekwe kwenye runner ambayo hukukusudia.

name: build
on:
  push:
    branches: [main]
jobs:
  build:
    runs-on: [self-hosted, linux, vps]
    steps:
      - uses: actions/checkout@v5
      - run: uname -a

Kazi ikisubiri kwenye Waiting for a runner to pick up this job, lebo hazilingani. Kila lebo iliyo katika runs-on lazima iwepo kwenye runner. Kwa hiyo, neno moja la ziada huacha kazi ikiwa kwenye foleni bila hitilafu yoyote kuonyeshwa. Linganisha orodha hiyo na lebo zinazoonyeshwa kando ya runner katika mipangilio ya hazina.

Kwa nini runners zinazojisimamia na hazina za umma haziendani

Hii ndiyo sehemu ambayo watu huiruka. Mwongozo wa GitHub uko wazi: runners zinazojisimamia "zinapaswa karibu kamwe kutotumiwa kwa hazina za umma", na "hazitoi hakikisho la kuendeshwa kwenye mashine pepe safi za muda mfupi, na zinaweza kuathiriwa kwa kudumu na msimbo usioaminika kwenye workflow".

Utaratibu huo ni rahisi. Pull request kutoka fork huleta nakala yake ya faili ya workflow. Ikiwa hazina yako ya umma inaendesha workflow za pull request kwenye runner yako, mtu yeyote anayeweza kufanya fork ya hazina hiyo anaweza kupendekeza workflow inayoendesha amri zake kwenye VPS yako. Hawahitaji ruhusa ya kuandika, kwa sababu wanachopendekeza ndicho kinachoendeshwa.

Mipangilio ya idhini hupunguza hatari hii bila kuirekebisha. Sera chaguo-msingi ya hazina ya umma humwomba maintainer aidhinishe workflow ya fork ya mchangiaji wa kwanza. Baada ya kumwidhinisha mtu huyo mara moja, pull request zake zinazofuata huendeshwa bila ombi jipya. Kwa hiyo, kizuizi ni mtu kusoma diff kila mara, na payload iliyofichwa ndani ya viwango vitatu vya script ya build inaweza kukosekana kwa urahisi.

Pull request ya fork haipokei secrets zako, na GITHUB_TOKEN yake ni ya kusoma tu. Hilo hupunguza uharibifu ndani ya GitHub. Halifanyi chochote kwa server yako. Mshambulizi ana shell akiwa gharunner, kwa hiyo anaweza kusoma kila faili ambayo mtumiaji huyo anaweza kusoma, kufikia chochote ambacho VPS inaweza kufikia kwenye mtandao wake binafsi, na kuacha kitu ndani ya ~/.bashrc au kwenye systemd unit ya mtumiaji inayoendeshwa wakati wa job inayofuata.

Kusajili kwa --ephemeral hufanya runner ikubali job moja kisha ijiondoe kwenye usajili, kwa hiyo job moja haiwezi kusoma workspace ya job inayofuata. Hii husaidia tu ikiwa kuna mchakato unaounda upya mashine au container kwa kila job, kwa sababu backdoor iliyoandikwa kwenye saraka ya nyumbani ya mtumiaji wa runner hubaki baada ya usajili mpya.

Sheria zinazofuata ni fupi. Tumia runners zinazojisimamia kwa hazina binafsi. Ikiwa lazima uunganishe moja kwenye hazina ya umma, usiendeshe pull request za fork juu yake, usiweke kitu kingine kwenye server hiyo, na ichukulie mashine hiyo kuwa ya kutupwa.

Kazi za Docker, na kundi ambalo kwa kweli ni root

Kazi za kontena, kontena za huduma na hatua yoyote ya mtiririko wa kazi inayotumia docker build zinahitaji daemon ya Docker kwenye seva mwenyeji ya runner. Sakinisha Docker kwa njia ya kawaida, kama ilivyoelezwa katika Docker na Docker Compose kwenye VPS, kisha ongeza mtumiaji wa runner kwenye kundi la docker.

Elewa athari kabla ya kufanya hivyo. Uanachama wa kundi la docker ni sawa na kuwa root, kwa sababu kontena linaweza kuunganisha / kama mount na kufanya kazi kama root ndani yake. Kwa hiyo, mtiririko wa kazi unaoweza kuwasiliana na socket ya Docker unaweza kusoma na kuandika kila faili kwenye VPS, ikiwemo /etc/shadow. Kwenye hazina binafsi yenye wachangiaji wanaoaminika, hilo linaweza kuwa gharama inayokubalika. Mahali pengine, huondoa sababu ya kutumia mtumiaji asiye na haki za kiutawala. Rootless Docker huweka miundo ya kontena ndani ya haki za mtumiaji mwenyewe wa runner, lakini hutumia storage driver ya polepole zaidi na hairuhusu kontena zenye haki za kipekee.

Masasisho, na kuondoa runner kwa usahihi

Runner inayojisimamia husasisha yenyewe kwa chaguo-msingi. Inatambua release mpya, inabadilisha faili zake yenyewe na kuwasha upya service, hivyo kwa kawaida huhitaji kufanya chochote. ./config.sh --disableupdate huzima usasishaji wa kiotomatiki unapohitaji toleo lisilobadilika. Baada ya hapo, jukumu la kusasisha ni lako: nyaraka za GitHub zinaeleza wazi kwamba runner iliyosanidiwa na --disableupdate lazima isasishwe mwenyewe.

Usasishaji wa mwenyewe huhifadhi usajili, kwa sababu .runner na .credentials hazipo kwenye tarball. Simamisha service, pakua tarball mpya na ukague checksum yake kama gharunner, itoae juu ya directory ileile kwa kutumia tar xzf, kisha uwashe service tena:

cd /home/gharunner/actions-runner
sudo ./svc.sh stop
sudo ./svc.sh start

Ili kuondoa runner, kwanza ondoa service, kisha iondoe kwenye usajili. Removal token inapatikana kwenye ukurasa huohuo wa Runners, chini ya kitufe cha Remove cha runner husika.

cd /home/gharunner/actions-runner
sudo ./svc.sh stop
sudo ./svc.sh uninstall
sudo -iu gharunner
cd ~/actions-runner
./config.sh remove --token PASTE_REMOVAL_TOKEN_HERE

Kufuta directory bila kuiondoa kwenye usajili huiacha runner ikiwa imeorodheshwa kama Offline kwenye repository, kwa sababu GitHub hutambua tu kwamba imeondolewa runner inapotoa taarifa hiyo au msimamizi anapofuta ingizo hilo mwenyewe.

Njia za kushindwa, pamoja na maandishi utakayoona

Must not run with sudo. config.sh huchapisha ujumbe huu na kujifunga inapotekelezwa kama root. Ukaguzi huu umewekwa kwa makusudi, kwa sababu faili zinazomilikiwa na root katika _work huharibu kila kazi inayofuata inayoendeshwa na mtumiaji wa huduma. Tekeleza ./config.sh kama gharunner. Kigezo cha RUNNER_ALLOW_RUNASROOT hupuuza ukaguzi huu, na kukitumia huhamisha tu tatizo hadi hatua ya baadaye.

sudo: ./svc.sh: command not found. Uko katika saraka sahihi. svc.sh bado haipo, kwa sababu config.sh haijakamilisha usajili. Sajili runner, kisha sakinisha huduma.

Http response code: NotFound from 'POST https://api.github.com/actions/runner-registration'. Token si token halali ya usajili. Huenda muda wake umeisha, kwa kuwa hudumu saa moja pekee, au umebandika personal access token badala ya token ya usajili kutoka ukurasa wa Runners. Tengeneza token mpya, kisha uibandike tena.

Dependencies is missing for Dotnet Core 6.0. Tekeleza sudo ./bin/installdependencies.sh kutoka katika saraka ya runner ukiwa root, kisha sajili tena.

Runner ikiwa Offline baada ya kuwasha upya. Tekeleza systemctl is-enabled 'actions.runner.*'. Ikiwa hakuna kilichoorodheshwa, ./svc.sh install haijawahi kutekelezwa, kwa hiyo runner ilikuwepo tu ndani ya kipindi cha terminal yako. Ikiwa unit imewezeshwa na runner bado iko Offline, soma journalctl -u 'actions.runner.*' na ukague HTTPS ya kutoka.

Diski inajaa. Checkout, akiba za build na picha za Docker hujilimbikiza katika _work na katika saraka ya nyumbani ya mtumiaji wa runner, na hakuna kinachoziondoa kiotomatiki kwa niaba yako. Fuatilia du -sh /home/gharunner/actions-runner/_work na uongeze usafishaji uliopangwa kabla diski haijalazimisha uufanye.

FAQ

Kwa nini sudo ./svc.sh install inasema amri haipatikani?

Kwa sababu svc.sh haipo kwenye runner tarball. Inatengenezwa kwenye saraka ya runner wakati ./config.sh inamaliza usajili, kwa kutumia jina la repository na runner yako kuunda jina la service. Endesha ./config.sh kwanza kama mtumiaji wa runner. Baada ya hapo, sudo ./svc.sh install gharunner itapata script na kuandika unit yenye jina actions.runner.OWNER-REPO.RUNNER-NAME.service kwenye /etc/systemd/system.

Je, ninahitaji kufungua port ya firewall kwa runner inayojidhibiti?

Hapana. Runner hufungua muunganisho wa HTTPS unaotoka kwenda GitHub na kuudumisha ikiwa wazi inapongoja kazi. Kwa hiyo, GitHub haianzishi muunganisho wowote kwenda kwenye VPS yako. Ruhusu mawasiliano yanayotoka kupitia 443 na uendelee kufunga sheria za mawasiliano yanayoingia. Ikiwa runner inaonyesha Offline wakati service yake inaendelea, chunguza uchujaji wa mawasiliano yanayotoka na DNS badala ya sheria za mawasiliano yanayoingia.

Je, ninaweza kutumia runner inayojidhibiti kwenye repository ya umma?

Unaweza, lakini GitHub haishauri kufanya hivyo. Pull request kutoka fork hubeba workflow file yake, kwa hiyo mtu yeyote anayeweza kuunda fork ya repository yako anaweza kupendekeza amri zitakazoendeshwa kwenye mashine yako. Ombi la idhini linahusu tu uendeshaji wa kwanza wa contributor. Ukiunganisha runner kwenye repository ya umma, zima fork pull request workflows kwenye runner hiyo, usihifadhi kitu kingine kwenye server hiyo, na ujenge upya mashine hiyo kwa ratiba maalumu.

Kwa nini usajili unashindwa kwa Http response code: NotFound?

Mwito wa usajili hujibu NotFound wakati credential si sahihi, si tu wakati URL si sahihi. Hilo hufanya ujumbe huo upotoshe. Registration tokens huisha muda saa moja baada ya kuonyeshwa, na personal access token haikubaliki kwa mwito huu. Fungua Settings, Actions, Runners, New self-hosted runner tena, nakili token mpya, na uthibitishe kuwa thamani ya --url inaelekeza kwenye repository ambayo una haki za usimamizi.