GitHub Actions

repo($path)->actions() ovláda GitHub Actions jedného repozitára: spustí workflow na refe, vráti run, ktorý GitHub spustil, umožní ho sledovať — jeho stav, joby aj kroky každého jobu — a zrušiť. GitLab a Bitbucket vyhodia FeatureNotSupportedException; ich pipeline balík nemapuje.

use RoundlyConsulting\Git\Enums\WorkflowStatus;
use RoundlyConsulting\Git\Facades\Git;

$actions = Git::github($credential)->repo('acme/infra')->actions();

$dispatched = $actions->dispatch('deploy.yml', 'refs/heads/main', ['request_id' => $id]);
$run = $actions->run($dispatched->runId);              // WorkflowRun
$run->isActive();                                       // poll until completed

$actions->runs('deploy.yml')->branch('main')->event('workflow_dispatch')
    ->status(WorkflowStatus::InProgress)->createdAfter($since)->get();   // Page<WorkflowRun>

$actions->jobs($run->id)->allAttempts()->lazy();        // WorkflowJob, with ->steps
$actions->jobs($run->id)->perPage(1)->get()->total;    // did the run start any job?
$actions->cancel($run->id);                             // true = accepted, false = already done

Každé id workflowu aj runu sa skontroluje ešte pred požiadavkou — id skončí v URL a ../7 či 7/jobs by oslovili iný zdroj. Workflow je názov jeho súboru (deploy.yml — jeden segment s koncovkou .yml alebo .yaml) alebo jeho číselné id a id runu tvoria len číslice; čokoľvek iné vyhodí OutOfScopeException. dispatch() a cancel() vyžadujú prihlasovacie údaje.

Spustenie workflowu

• $ref sa odošle tak, ako ho zadáte — funguje main aj refs/heads/main. $inputs sú vstupy, ktoré workflow deklaruje, každý ako reťazec, číslo alebo boolean; pozičný kľúč, vnorená hodnota či null vyhodí InvalidArgumentException. Koľko vstupov workflow prijme, určí odpoveď 422 z GitHubu, nie limit na strane klienta.
• Na github.com a GHE.com GitHub odpovie runom, ktorý spustil, takže runId, apiUrl aj url sú vyplnené. GitHub Enterprise Server túto odpoveď nezdokumentoval, preto sú tam všetky tri null — run nájdete postupom nižšie.
• dispatchedAt je lokálny čas prečítaný ešte pred odoslaním požiadavky, takže dopyt od tohto času run nemôže minúť.
• Spustenie sa nikdy neopakuje: stratená odpoveď a následné opakovanie by spustili druhý build.

Nájdenie runu bez runId

Na GitHub Enterprise Server, alebo keď preberáte run spustený inde, vložte do run-name workflowu značku — run-name: deploy [${{ inputs.request_id }}] — a hľadajte ju medzi runmi vytvorenými od spustenia:

use RoundlyConsulting\Git\Dto\WorkflowRun;

// .github/workflows/deploy.yml — run-name: deploy [${{ inputs.request_id }}]
$candidates = $actions->runs('deploy.yml')
    ->event('workflow_dispatch')
    ->branch('main')
    ->createdAfter($dispatched->dispatchedAt->copy()->subMinute())
    ->get();

$run = $candidates->collect()->first(fn (WorkflowRun $run) => str_contains($run->displayTitle, "[{$id}]"));

Pravidlá párovania — aká značka, najstarší alebo najnovší run, ďalšie kontroly path či headBranch — zostávajú na vás; balík kvôli nim nerobí žiadne ďalšie volanie API.

Dopyty na runy a joby

• runs() filtruje cez branch(), event(), status(), actor() (login), headSha(), createdAfter() a createdBefore(). status() prijme WorkflowStatus aj WorkflowConclusion — GitHub berie oboje v jednom filtri — a pre Unknown vyhodí InvalidArgumentException.
• createdAfter() a createdBefore() porovnávajú v UTC na sekundy a vašu inštanciu Carbon nikdy neposunú. excludePullRequests() len vynechá pull_requests každého runu z odpovede GitHubu — nič nefiltruje.
• total stránky je total_count z GitHubu. GitHub filtrované vyhľadávanie runov zastaví na 1 000 výsledkoch, takže tam skončí aj lazy() — total väčší, než koľko ste prečítali, vás na to upozorní.
• jobs() číta posledný pokus runu; allAttempts() číta všetky pokusy a attempt($n) jeden z nich (1 je prvé spustenie). Obe naraz alebo pokus menší ako 1 vyhodia InvalidArgumentException.

Sledovanie a rušenie

• run($id) prechádza podmienenou cache, takže pri GIT_CACHE_ENABLED=true sa nezmenený run vráti ako 304, ktorú GitHub nezapočítava do primárneho limitu.
• isActive() platí pre všetko okrem completed — vrátane stavu Unknown —, takže sledovanie sa nikdy nezastaví na stave, ktorý nevie prečítať. Stav alebo výsledok, ktorý GitHub pridá neskôr, sa prečíta ako Unknown a nikdy sa nepočíta za dokončený ani úspešný.
• runStartedAt je čas vytvorenia, kým run čaká (queued, waiting); spoľahnite sa naň až vtedy, keď run beží.
• GitHub ruší asynchrónne: true znamená, že zrušenie prijal, a výsledok ukáže ďalšie run() (wasCancelled()). false znamená, že run už skončil. Vynútené zrušenie (force-cancel) balík neponúka.

Výsledné objekty

Payload runu alebo jobu bez použiteľného id vyhodí InvalidArgumentException s názvom poľa — id si balík nikdy nevymyslí.

Oprávnenia

Obmedzený token GitHub App potrebuje pre jednotlivé volania tieto oprávnenia:

use RoundlyConsulting\Git\Dto\Credentials\GithubAppToken;
use RoundlyConsulting\Git\Dto\Input\InstallationTokenScope;

$credential = GithubAppToken::for($appId, $installationId, $privateKey)->forScope(
    new InstallationTokenScope(repositories: ['acme/infra'], permissions: ['actions' => 'write']),
);

Git::github($credential)->repo('acme/infra')->actions()->dispatch('deploy.yml', 'main');