potherca/flysystem-github
Flysystem adapter for GitHub. Use a GitHub repository as a filesystem backend, reading, writing, listing, and deleting files through Flysystem's simple API while the package handles the underlying GitHub API calls. Useful for storing content, configs, or docs directly in a repo.
Architecture fit. potherca/flysystem-github implements a Flysystem adapter that presents a GitHub repository as a filesystem. In a Laravel context that means exposing it through Storage as a custom disk. Architecturally, GitHub is a poor substitute for object/block storage: it is API-backed, commit-oriented, branch-scoped, rate-limited, and not designed for high-frequency or arbitrary file mutation. The adapter is a reasonable fit only for narrow, read-heavy or low-write use cases—publishing versioned content, syncing documentation/config into a repo, or treating a repo as a curated artifact store. It is not a fit for session storage, uploads, caches, queues, or any workload requiring atomic writes, low latency, or high concurrency.
Integration feasibility. The package's last release was April 2016, which places it in the Flysystem 1.x era and the Laravel 5.x generation. Modern Laravel uses Flysystem 3.x with a different adapter contract (League\Flysystem\FilesystemAdapter, Config, typed methods) and a different Storage::extend registration pattern. Out-of-the-box compatibility with Laravel 9/10/11 is therefore unlikely without a fork or bridge. The repository is unknown, stars are low (11), and the opportunity score (0.38) suggests limited strategic upside. MIT licensing is permissive, so forking and porting is legally straightforward, but it becomes an owned code asset rather than a maintained dependency.
Technical risk. High. The package is effectively unmaintained, predates multiple GitHub API and authentication changes, and likely has no CI or compatibility matrix. GitHub's Contents API imposes file-size limits, commit-per-write behavior, branch protection interactions, and rate limits; the adapter's handling of these is unverified. Token handling, retry behavior, binary/LFS support, and concurrent write semantics are unknown. Committing on every write can bloat repository history and trigger CI unnecessarily.
Key questions.
url(), temporaryUrl(), visibility, and directory listing in a way Laravel's Storage contract expects?Stack fit. The natural integration is a custom Laravel disk registered via Storage::extend, with credentials in config/filesystems.php and a scoped token in the environment. That fits Laravel's abstraction cleanly if the adapter satisfies Flysystem 3. If it does not, the integration is a fork-and-port effort, not a Composer install.
Migration path. Do not introduce this directly into a production Laravel application. Run a time-boxed spike in an isolated branch or sandbox app against a disposable GitHub repository with a minimally scoped token. Evaluate two paths: (1) fork and port the adapter to Flysystem 3, or (2) bypass Flysystem entirely and implement the specific operations with a GitHub API client inside a queued job. For read-only publishing or documentation sync, path 2 is usually cheaper and lower risk. For teams that genuinely need a Storage disk, path 1 preserves the Laravel abstraction at the cost of owning adapter code.
Compatibility. Assume no compatibility with current Laravel until proven. Check composer.json constraints, Flysystem interface signatures, PHP version requirements, and Guzzle version. The 2016 release likely targets PHP 5.5/7.0 and Flysystem 1.x; running it on PHP 8.x will surface deprecations and possibly fatal signature mismatches. A compatibility matrix should cover Laravel version, Flysystem major, PHP version, and GitHub API version before any adoption decision.
Sequencing.
Storage API for the operations actually needed.Maintenance. The package is abandoned by practical standards: last release 2016, 11 stars, unknown repository. Adopting it means owning it. Budget for a named maintainer, a fork under the organization, dependency pinning, and periodic review against GitHub API changes. This is a non-trivial ownership cost for a small adapter.
Support. There is no meaningful community or vendor support. Internal documentation, runbooks, and tests become the support layer. Escalation paths are limited to the team that forked the code.
Scaling. GitHub API rate limits (typically 5,000 authenticated requests per hour), per-request latency, and commit-per-write behavior make this unsuitable for high-throughput workloads. Directory listings and recursive operations can multiply API calls. Repository size, file size, and history growth are practical ceilings. Plan for caching reads and batching or debouncing writes.
Failure modes. Expect rate-limit 403s, expired or mis-scoped tokens, branch protection rejections, merge conflicts from concurrent writers, partial writes, network timeouts, API deprecations, and cache inconsistency between GitHub and the application. Writes are not atomic; retries must be idempotent or deduplicated. CI triggered by adapter commits can create feedback loops. Monitoring should cover API error rates, rate-limit headroom, commit volume, and token expiry.
Ramp-up. The code surface is small, so ramp-up is mostly domain knowledge: Flysystem adapter internals, Laravel's Storage contract, and GitHub's Contents API semantics. Expect a few days for a spike and one to two weeks for a hardened fork with tests. The larger cost is ongoing ownership, not initial integration.
TPM recommendation. Treat this as an evaluation candidate, not an adoption. Leverage it only for low-risk, read-heavy, versioned-content scenarios, and only after a fork-and-port spike proves compatibility. For most Laravel teams, a thin GitHub API client in a queued job delivers the same business outcome with less architectural impedance and lower long-term ownership risk.
How can I help you explore Laravel packages today?