Konfigurácia
Publikovaný config/git.php obsahuje jeden blok pre každého providera a spoločné bloky pre cache, logovanie, webhooky a dávky. Blok GitHubu celý, GitLab a Bitbucket skrátené tam, kde opakujú rovnakú štruktúru:
return [
'providers' => [
'github' => [
'url' => env('GITHUB_API_URL', 'https://api.github.com'),
'token' => env('GITHUB_TOKEN'),
'webhook_secret' => env('GITHUB_WEBHOOK_SECRET'),
'timeout' => env('GITHUB_TIMEOUT', 10),
'retry' => [
'times' => env('GITHUB_RETRY_TIMES', 1),
'backoff' => env('GITHUB_RETRY_BACKOFF', 0),
],
'rateLimits' => [
'enabled' => env('GITHUB_RATELIMIT_ENABLED', true),
'owner' => env('GITHUB_RATELIMIT_OWNER', 'app'),
'maxAttempts' => env('GITHUB_RATELIMIT', 5000),
'timespan' => env('GITHUB_RATELIMIT_TIMESPAN', 'hour'), // second | minute | hour | day
'adaptive' => env('GITHUB_RATELIMIT_ADAPTIVE', true),
'max_wait' => env('GITHUB_RATELIMIT_MAX_WAIT'), // ms; null = wait/pace
'jitter' => env('GITHUB_RATELIMIT_JITTER'), // ms; null = none
],
'options' => [
'headers' => [
'User-Agent' => env('GIT_USER_AGENT', env('APP_NAME', 'GitHttp/1.0')),
'X-GitHub-Api-Version' => env('GITHUB_API_VERSION', '2022-11-28'),
],
],
// GitHub App authentication (self-refreshing installation tokens).
// When id, installation_id and private_key are all set, Git::github() mints
// installation tokens automatically; otherwise it uses token.
// Git::githubApp() needs only id + private_key.
'app' => [
'id' => env('GITHUB_APP_ID'),
'installation_id' => env('GITHUB_APP_INSTALLATION_ID'),
'private_key' => env('GITHUB_APP_PRIVATE_KEY'), // PEM string or file path
'slug' => env('GITHUB_APP_SLUG'), // builds the install URL
'permissions' => [ // default scope for a per-operation mint
'contents' => 'write',
'pull_requests' => 'write',
'metadata' => 'read',
],
],
// OAuth credentials (self-refreshing access tokens).
'oauth' => [
'client_id' => env('GITHUB_OAUTH_CLIENT_ID'),
'client_secret' => env('GITHUB_OAUTH_CLIENT_SECRET'),
'token_url' => env('GITHUB_OAUTH_TOKEN_URL', 'https://github.com/login/oauth/access_token'),
],
],
'gitlab' => [
'url' => env('GITLAB_API_URL', 'https://gitlab.com'),
'token' => env('GITLAB_TOKEN'),
'webhook_secret' => env('GITLAB_WEBHOOK_SECRET'),
// timeout, retry and options follow the same shape with GITLAB_* keys
'rateLimits' => [
'maxAttempts' => env('GITLAB_RATELIMIT', 10),
'timespan' => env('GITLAB_RATELIMIT_TIMESPAN', 'second'),
// enabled, owner, adaptive, max_wait, jitter as above
],
'oauth' => [
'client_id' => env('GITLAB_OAUTH_CLIENT_ID'),
'client_secret' => env('GITLAB_OAUTH_CLIENT_SECRET'),
'token_url' => env('GITLAB_OAUTH_TOKEN_URL', 'https://gitlab.com/oauth/token'),
],
],
'bitbucket' => [
'url' => env('BITBUCKET_API_URL', 'https://api.bitbucket.org'),
'token' => env('BITBUCKET_TOKEN'),
'webhook_secret' => env('BITBUCKET_WEBHOOK_SECRET'),
// timeout, retry and options follow the same shape with BITBUCKET_* keys
'rateLimits' => [
'maxAttempts' => env('BITBUCKET_RATELIMIT', 1000),
'timespan' => env('BITBUCKET_RATELIMIT_TIMESPAN', 'hour'),
],
],
],
'cache' => [
'enabled' => env('GIT_CACHE_ENABLED', false),
'store' => env('GIT_CACHE_STORE'),
'ttl' => env('GIT_CACHE_TTL', 3600),
],
'logging' => [
'enabled' => env('GIT_LOGGING_ENABLED', false),
'channel' => env('GIT_LOGGING_CHANNEL'),
],
'webhooks' => [
// Handed over raw and parsed strictly where it is read: 1/true/on/yes enable the
// route, 0/false/off/no keep it off, and anything else throws at boot.
'enabled' => env('GIT_WEBHOOKS_ENABLED', false),
'path' => env('GIT_WEBHOOKS_PATH', 'git/webhooks'),
'middleware' => ['api'],
],
'batch' => [
'concurrency' => env('GIT_BATCH_CONCURRENCY', 25),
],
];Všetky kľúče
| Kľúč | Predvolené | Účel |
|---|---|---|
providers.<name>.url | URL API platformy | Základná URL API — api.github.com, gitlab.com, api.bitbucket.org. Pre GitHub Enterprise Server zadajte https://ghe.example.com/api/v3; clone a inštalačné URL sa potom zostavia na webovom hostiteľovi https://ghe.example.com. Bez nastavenia alebo pri prázdnej hodnote (GITHUB_API_URL=) sa použije verejné API; hodnota, ktorá nie je reťazcom, vyhodí výnimku. |
providers.<name>.token | null | Predvolený prístupový token — Git::github() a spol. ho použijú, keď neodovzdáte žiadne prihlasovacie údaje. |
providers.<name>.webhook_secret | null | Overuje prichádzajúce webhooky; zároveň predvolené tajomstvo pri registrácii webhooku. Nenastavené alebo prázdne znamená žiadne tajomstvo, takže sa nič neoverí. |
providers.<name>.timeout | 10 | Časový limit HTTP požiadavky v sekundách, 0–3600 (0 = bez limitu). |
providers.<name>.retry.times | 1 | Počet pokusov (0–100) pri čítaní, ktoré narazí na prerušené spojenie, 429 alebo 5xx; zápisy sa nikdy neopakujú. retry môže byť aj obyčajné celé číslo — počet pokusov. |
providers.<name>.retry.backoff | 0 | Pauza medzi opakovaniami čítania v ms (0–600000). |
providers.<name>.rateLimits.enabled | true | Klientske obmedzovanie; false posiela požiadavky úplne bez limitera. |
providers.<name>.rateLimits.owner | app | Kľúč skupiny limitu (git:<provider>:<owner>). Prázdna hodnota sa považuje za nenastavenú (app); hodnota, ktorá nie je reťazcom, vyhodí výnimku. |
providers.<name>.rateLimits.maxAttempts | 5000 / 10 / 1000 | Počet požiadaviek za časové okno, aspoň 1 (GitHub / GitLab / Bitbucket). |
providers.<name>.rateLimits.timespan | hour / second / hour | second, minute, hour alebo day; čokoľvek iné vyhodí výnimku (nenastavený alebo prázdny kľúč znamená minute). |
providers.<name>.rateLimits.adaptive | true | Rešpektovať vlastné hlavičky platformy Retry-After / X-RateLimit-*. |
providers.<name>.rateLimits.max_wait | null | Maximálne odloženie v ms (0 alebo viac) pred okamžitým zlyhaním; null alebo prázdna hodnota namiesto toho čaká a rozkladá požiadavky. |
providers.<name>.rateLimits.jitter | null | Náhodný rozptyl v ms (0 alebo viac) pridaný ku každému odloženiu; null alebo prázdna hodnota nepridá žiadny. |
providers.<name>.options.headers | User-Agent | Doplnkové HTTP voľby pre každú požiadavku; GitHub navyše pripína X-GitHub-Api-Version 2022-11-28. |
providers.github.app.id | null | Id GitHub App; ak sú nastavené aj installation_id a private_key, Git::github() vydáva inštalačné tokeny. Nenastavené alebo prázdne znamená, že aplikácia nie je nakonfigurovaná; hodnota, ktorá nie je reťazcom (napríklad celé číslo), vyhodí výnimku s názvom kľúča namiesto návratu k token. |
providers.github.app.installation_id | null | Id inštalácie pre predvolené prihlásenie aplikácie. |
providers.github.app.private_key | null | Privátny kľúč aplikácie — PEM reťazec alebo cesta k súboru. |
providers.github.app.slug | null | Verejný slug aplikácie; vyžaduje ho installUrl(). |
providers.github.app.permissions | contents, pull_requests: write; metadata: read | Sada oprávnení, ktorú používa InstallationTokenScope::forRepositories(). |
providers.<github|gitlab>.oauth.client_id | null | OAuth client id, ktoré číta OauthToken::forProvider(). |
providers.<github|gitlab>.oauth.client_secret | null | OAuth client secret, ktoré číta OauthToken::forProvider(). |
providers.<github|gitlab>.oauth.token_url | Token URL platformy | OAuth endpoint na obnovu prístupových tokenov. |
cache.enabled | false | Ukladať ETagy a odpovede 304 Not Modified obsluhovať z cache. |
cache.store | Predvolený store | Cache store pre podmienené požiadavky aj pre vydané App/OAuth tokeny. Prázdna hodnota sa považuje za nenastavenú (predvolený store); hodnota, ktorá nie je reťazcom, vyhodí výnimku. |
cache.ttl | 3600 | Platnosť uloženej odpovede v sekundách, aspoň 1. |
logging.enabled | false | Logovať metódu, URL, stav a trvanie na úrovni debug — nikdy tokeny ani telá požiadaviek. |
logging.channel | Predvolený kanál | Log kanál pre logovanie požiadaviek. Prázdna hodnota sa považuje za nenastavenú (predvolený kanál); hodnota, ktorá nie je reťazcom, vyhodí výnimku. |
webhooks.enabled | false | Zaregistrovať webhook routu POST {path}/{provider}. Nenastavené alebo prázdne (GIT_WEBHOOKS_ENABLED=null, GIT_WEBHOOKS_ENABLED=) znamená vypnuté — pre routu, pre URL, ktorú odvodí webhooks()->register(), aj pre about. |
webhooks.path | git/webhooks | Základná cesta webhook routy. Prázdna hodnota sa považuje za nenastavenú a použije sa git/webhooks; okrajové lomky sa orežú (/hooks/ je hooks); cesta len z lomiek alebo hodnota, ktorá nie je reťazcom, vyhodí výnimku — nikdy koreň webu. |
webhooks.middleware | ['api'] | Middleware aplikované na webhook routu. |
batch.concurrency | 25 | Maximum súbežných požiadaviek v jednom poole (1–1000); väčšie vstupy sa rozdelia na časti. |
Prostredie (env)
Bežné nastavenia sa riadia cez env, takže väčšina aplikácií konfiguráciu vôbec nepublikuje:
GITHUB_TOKEN=ghp_...
GITLAB_TOKEN=glpat-...
BITBUCKET_TOKEN=...
GITHUB_WEBHOOK_SECRET=...
GIT_WEBHOOKS_ENABLED=true
GIT_CACHE_ENABLED=true
GIT_CACHE_STORE=redis
GIT_LOGGING_ENABLED=true- Tokeny a tajomstvá: GITHUB_TOKEN, GITLAB_TOKEN, BITBUCKET_TOKEN a príslušné *_WEBHOOK_SECRET.
- Prenos pre každého providera: *_API_URL, *_TIMEOUT, *_RETRY_TIMES, *_RETRY_BACKOFF a kľúče *_RATELIMIT*.
- GitHub App: GITHUB_APP_ID, GITHUB_APP_INSTALLATION_ID, GITHUB_APP_PRIVATE_KEY, GITHUB_APP_SLUG.
- OAuth: GITHUB_OAUTH_CLIENT_ID, GITHUB_OAUTH_CLIENT_SECRET, GITHUB_OAUTH_TOKEN_URL a ekvivalenty pre GitLab.
- Spoločné: GIT_CACHE_ENABLED, GIT_CACHE_STORE, GIT_CACHE_TTL, GIT_LOGGING_ENABLED, GIT_LOGGING_CHANNEL, GIT_WEBHOOKS_ENABLED, GIT_WEBHOOKS_PATH, GIT_BATCH_CONCURRENCY, GIT_USER_AGENT, GITHUB_API_VERSION.
.env dodáva každú hodnotu ako reťazec a balík ju číta podľa toho, čo vyjadruje: celočíselný kľúč prijme číselný reťazec (GITHUB_TIMEOUT=45 je 45 sekúnd) a ak hodnota nie je celé číslo v povolenom rozsahu, vyhodí InvalidConfigurationException z package-toolkit s názvom kľúča; booleovský kľúč číta 1/true/on/yes ako zapnuté a 0/false/off/no ako vypnuté — GIT_WEBHOOKS_ENABLED=off teda naozaj vypína — a pri čomkoľvek inom vyhodí rovnakú výnimku (GIT_WEBHOOKS_ENABLED=disabled zlyhá pri štarte namiesto toho, aby routu potichu nechal vypnutú). Rovnako to platí pre všetky ostatné nastavenia: timespan mimo second/minute/hour/day, max_wait či jitter, ktoré nie sú celým číslom, a reťazcové nastavenie, ktoré nie je reťazcom, vyhodia výnimku s názvom kľúča. Predvolenú hodnotu dostane len kľúč, ktorý nie je nastavený — chýba, je null alebo je prázdny (riadok KEY= v hostiteľskej aplikácii) —, prípadne zostane vypnutý, ak je voliteľný.
App a OAuth tokeny sa kešujú, aby prežili medzi požiadavkami — ak ich používate, nasmerujte cache.store na zdieľaný store (Redis, databáza, súbor), nie na driver array.
Prejavte lásku k open source
Tento balík je zadarmo pod licenciou MIT. Ak vám šetrí čas, jednorazový príspevok alebo členstvo na Patreone nám pomôže ho ďalej udržiavať, testovať a dokumentovať.
Ďalšie spôsoby podpory vrátane kryptomienOdoslaním daru súhlasíte s našimi podmienkami prijímania darov.
Chcete to zabudovať do svojho produktu?
Naše balíky integrujeme do zákazkových Laravel a AI riešení. Napíšte nám, na čom pracujete, a ozveme sa do 48 hodín.