Product Decisions This Supports
- Build vs. buy on source-control integration. The package removes the commodity portion of a Gitea integration — token auth, request construction, response parsing across users, organisations, repositories, issues, and webhooks — converting a "weeks of HTTP plumbing" estimate into "days of application logic." That reframing is the PM lever: it makes a Gitea spike cheap enough to fund now instead of deferring a quarter, and it's the fastest way to answer whether internal Gitea tooling is viable at all.
- Self-hosted vs. SaaS source control. Every "we can't integrate with it from our stack" objection is a hidden tax on a platform bet. A workable PHP client lowers switching cost away from GitHub/GitLab and turns the Gitea case — data residency, air-gapped deployment, compliance, licence cost — into an operations argument rather than an engineering-feasibility one.
- Roadmap scope it unlocks. Concretely: auto-provisioning repos, teams, and webhooks on hire; org and repository templating; issue/PR mirroring into an internal dashboard; release-note generation; bulk migration scripts off GitHub or GitLab; and scheduled archival of issues, releases, and repo metadata for audit and retention — the last being a recurring ask anywhere Gitea sits inside a regulated environment.
- Integration tiering and honest staffing. The adoption signal is weak: zero dependents, negligible stars, low opportunity score. The decision this supports is classification — Gitea belongs in the niche integration tier, funded as a time-boxed spike when a customer or internal team asks, not staffed as a first-class always-on surface.
- Sizing the platform bet. If strategy assumes Gitea, this package is evidence the PHP ecosystem around it is thin. Plan to own more of the integration layer than you would on GitHub — pagination, retries, rate-limit backoff, webhook verification, DTO gaps — and carry that ownership on the roadmap as cost rather than treating the dependency as free.
When to Consider This Package
Adopt it when:
- You already operate a Gitea instance and the consuming application is PHP/Laravel. Without an existing deployment there is no reason to start here.
- The integration is internal-facing and moderate-volume — admin tooling, sync jobs, migration scripts, dashboards — not a public API gateway or latency-critical path.
- You need breadth more than depth across users, orgs, repos, issues, webhooks, and releases. For one or two endpoints, a thin in-house client is lower risk than a dependency.
- You will wrap it behind your own interface from day one, pin the version exactly, and accept that you may fork or vendor it.
Look elsewhere — or build in-house — when:
- Maintenance confidence is a requirement. Zero dependents and a low opportunity score are due-diligence red flags: no visible community, no evidence of downstream production use, no support contract. Assume a bus factor of one.
- You need an SLA, security responsiveness, or someone to escalate to. Use the Gitea HTTP API directly, the official Go client, or a commercial integration platform.
- You need full, strongly-typed coverage tracking current Gitea releases. Community wrappers lag upstream; the shipped resource classes are the de facto feature list, and anything outside them becomes your code.
- Your stack is not PHP, or your volume and latency profile makes an unbenchmarked wrapper a performance unknown.
- You're integrating with GitHub or GitLab — mature official clients exist and this package is irrelevant.
How to Pitch It (Stakeholders)
To executives: This is a small, free, open-source PHP library that lets our application talk to a self-hosted Gitea server without us building that plumbing ourselves — the difference between a two-week spike and a two-month project for any Gitea-adjacent feature. Cost is near zero; so is the adoption signal, so treat it as a prototype enabler, not a foundation. Recommendation: fund a short, strictly time-boxed spike, keep the library behind our own abstraction layer so it can be swapped without a rewrite, and budget a small named maintenance owner plus periodic version-compatibility review.
To engineering: An object-oriented client over the Gitea REST API, installable via Composer and built on Saloon, so it composes naturally with Laravel's container, HTTP client, and queue layers. It removes boilerplate for token auth, request building, and response mapping across users, orgs, repos, issues, and webhooks — and because it ships no service provider or facade, there's no framework coupling to unwind later. Plan around the caveats: lowest-tier maintenance signal, likely lag against upstream Gitea versions, no built-in retry or rate-limit handling, and no guarantees on pagination completeness or error semantics (->throw() is not automatic). Bind the connector as a singleton with the base URL including /api/v1, wrap it in narrow domain services so no Saloon Response reaches a controller, push every write to a queued job with idempotency guards, verify webhooks against the raw request body, and test with Saloon's MockClient rather than Http::fake(). Build the reconciliation command early — it is both a feature and the recovery mechanism for every partial-failure mode.