- How do I install owenvoke/gitea in a Laravel application?
- Install it with Composer by running composer require owenvoke/gitea. The package is framework-agnostic and ships no service provider, facade, or publishable config, so the only extra wiring is a config/services.php entry for the Gitea base URL (including /api/v1), token and timeout, plus a singleton binding in AppServiceProvider. After that you can inject the connector, or your own domain wrapper around it, anywhere in the application.
- Does owenvoke/gitea work with Laravel 10 and 11, and which PHP version does it require?
- The package requires PHP 8 or newer and has no Laravel-specific dependency, so it works on Laravel 9, 10, 11 and 12 alike as long as the PHP requirement is met. It is built on Saloon, so the framework compatibility you really need to verify is Saloon's. Pin an exact package version rather than a floating constraint, and keep a PATCHES.md if you vendor a fork.
- How do I authenticate the Gitea API client with an access token?
- Create a token in your Gitea instance under Settings, Applications, then pass it to the connector, typically as a bearer or token header in the connector's default headers. Store it per environment in config/services.php backed by an environment variable rather than hard-coding it. Token scope is the most common cause of calls that worked yesterday failing today, so check scope before debugging code when a batch dies mid-run.
- How do I create an issue or fetch a repository with owenvoke/gitea?
- Instantiate the connector with your base URL and token, then use the resource classes: the repositories resource for reads such as fetching a repo, and the issues resource for writes such as creating an issue. A short spike that performs one write and one cheap read exercises authentication, JSON POST and response parsing, and gives a clear go or no-go signal. Keep those calls inside a domain service such as GiteaIssues or GiteaRepositories rather than calling the connector directly from controllers or jobs.
- Which Gitea API endpoints and resources does the package support?
- Coverage is driven by the resources in src/Resources, and the common ones are repositories, issues, users, organizations and webhooks. Anything not implemented there is code you write yourself, and DTO coverage in src/Data is partial, so expect some responses to arrive as raw arrays. Check the resource directory before committing to a minimum endpoint set for your first release.
- Does owenvoke/gitea handle rate limits, retries, or throw exceptions on API errors?
- No. There are no built-in retries, backoff, rate-limit handling or automatic throwing, so 429 storms and confusing null responses on 404s are your responsibility. Configure an always-throw discipline on the connector or call throw() explicitly, and add your own retry logic where it matters. Logging the fully resolved request URL once during a spike makes auth failures and base-URL 404s easy to tell apart.
- How should I test code that calls the Gitea API with this package?
- Use Saloon's MockClient to fake responses rather than Laravel's Http::fake(), which bypasses Saloon entirely and can let real requests through silently in CI. Record a handful of representative payloads, one write such as creating an issue and one cheap read such as fetching a repository, and assert against your own value objects instead of Saloon responses. A non-production Gitea instance is also worth having for occasional contract testing.
- Why am I getting 404 or authentication errors connecting to my Gitea instance?
- The most common cause is the base URL: it must include /api/v1, and a trailing slash or bare host produces 404s that read like authentication failures. Self-signed certificates on internal Gitea instances are the second common cause, so scope any TLS verification bypass to the Gitea connector's Guzzle options and never globally. Log the resolved URL once at boot to confirm exactly what is being requested.
- How do I paginate through Gitea API results reliably with this client?
- Pagination completeness is not guaranteed, and the X-Total-Count header may be absent depending on the endpoint or Gitea version. Loop until you receive an empty page instead of trusting a reported total, and add a runaway cap so a misbehaving endpoint cannot spin forever. Keep that logic inside your own wrapper so controllers and jobs never deal with pagination details.
- Is owenvoke/gitea safe to depend on in production, or are there better alternatives?
- It is a thin Saloon connector with a single maintainer, negligible stars and zero dependents, so treat the dependency risk as real: pin an exact version and write a fork-and-vendor trigger into your decision record. It fits internal tooling and automation well but not latency-critical or SLA-bearing paths. Wrap it behind one narrow domain service per noun from day one, returning your own value objects and scalars, so swapping to direct Guzzle calls or another Gitea SDK means changing method bodies only.