Flysystem Gitlab Storage Laravel Package

Technical Evaluation

Architecture Fit

royvoetman/flysystem-gitlab-storage is a thin League\Flysystem\FilesystemAdapter that translates Flysystem operations into GitLab Repository Files API v4 calls. For a Laravel application this is the correct architectural seam: application code talks to Storage::disk(...), the disk resolves to a Flysystem Filesystem, and the GitLab adapter is a swappable implementation detail configured in config/filesystems.php. No domain code should ever reference GitLab.

The decisive architectural fact is that this is a Git repository, not an object store. Every write is a commit on the configured branch. Directory creation is emulated with .gitkeep files (v1.0.0). Listing is a paginated tree walk (v1.1.0). There is no native file-level locking, no multipart upload path, and — despite common assumptions — no evidence of Git LFS support in the README or changelog; assume large files land in the repository proper until proven otherwise. That makes this adapter a good fit for low-churn, version-controlled artifacts and static exports, and a poor fit for user uploads, caches, session data, or anything written per-request. "Use GitLab as our storage backend" is a product decision with second-order effects on repository size, clone times, CI runner performance, and backup strategy — not merely a config change.

Integration Feasibility

• Install is one Composer package; the Laravel disk driver lives in a separate package, royvoetman/laravel-gitlab-storage. Two dependency surfaces for one capability, each with its own release cadence and maintainer attention.
• If the bridge is stale, writing a custom driver is cheap: a service provider calling Storage::extend('gitlab', ...) around the adapter. Estimate 1–2 days including tests. Do not let the bridge be a gate.
• Construction is explicit and environment-friendly: project ID, branch, base URL, personal access token, optional path prefix. All four map cleanly onto env() values and a 12-factor secrets story.
• branch is the effective "bucket" analogue. That is a genuinely useful isolation primitive (per-environment or per-tenant branches) and a live footgun if it defaults to main in production.

Technical Risk

Key Questions

1. What is projected write volume and file-size distribution over 12 months? A few thousand small objects is defensible; per-request writes or multi-MB blobs are not.
2. Is the requirement "files must live in GitLab" or "files must stay in our infrastructure"? The latter is satisfied by MinIO or S3-compatible storage with none of these tradeoffs.
3. Who owns PAT lifecycle — issuance, scoping, rotation cadence, revocation runbook?
4. Which Flysystem major does our Laravel version resolve to, and does the Laravel bridge declare a compatible constraint?
5. Does the adapter implement copy/move natively or emulate them as read-then-write? This drives both latency and failure modes.
6. Which self-hosted GitLab versions are in scope, and has v4 endpoint and pagination behaviour been validated against ours?
7. Do we require read-after-write consistency or atomic multi-object operations? A commit-per-write model provides neither.
8. Are path prefixes tenant-isolated, or can a caller traverse out of its prefix?

Integration Approach

Stack Fit

• Composer package + a disk entry in config/filesystems.php; consumption via the Storage facade keeps the application backend-agnostic and preserves future portability.
• Supported lane: PHP 8.1+, Flysystem ^3 (Laravel 9–12), GitLab API v4 including self-hosted via configurable base URL.
• The path/prefix constructor argument maps naturally to per-environment or per-tenant scoping inside one repository — use it deliberately rather than sharing a root.
• The adapter is one class plus a small API client; the realistic failure mode is "we own it now," and the codebase is small enough that owning it is acceptable.

Migration Path

• Because Flysystem normalizes the interface, migration is a disk-config swap plus a data-movement job — no application-layer rewrite for callers already using Storage.
• Move data in batched commits. Thousands of individual writes means thousands of commits and near-certain rate limiting.
• Run a shadow-read period: dual-write to old and new disks, serve reads from the old disk, diff outputs, then flip. Flysystem's multi-adapter composition makes this a configuration exercise rather than a code change.
• Scope the migration to an append-only workload class (build artifacts, generated exports, static assets). Explicitly exclude high-churn and transactional data from phase one.

Compatibility

• Declare Laravel 9+ / Flysystem 3 / PHP 8.1+ as the supported lane and decline the v2.0.4 / v1.1.0 lines outright — pinning an adapter two majors behind is a compounding liability.
• Pin ^3.1.1 at minimum and add a regression test asserting that paths containing spaces, +, #, and non-ASCII characters round-trip. This bug class is exactly what a low-star package will not catch for us.
• Validate against our actual self-hosted GitLab version during the spike, not against gitlab.com.
• Confirm the Laravel bridge declares Flysystem 3 and a Laravel constraint overlapping ours; otherwise skip it and write the driver.

Sequencing

1. Spike (1 week): disposable GitLab project; exercise put/get/list/delete/copy/move with pathological paths, paginated listings, and multi-MB files; record commit counts and rate-limit behaviour.
2. Driver decision (3–5 days): validate the Laravel bridge or land a service-provider driver. Do not block on the bridge.
3. Conformance and fault injection: 401/403/404/429/5xx; verify retry does not duplicate writes; verify streamed reads stay memory-bounded (v2.0.2/2.0.3 suggest stream handling has been fragile historically).
4. Observability before rollout: emit metrics for request count, 429 rate, commit count per operation, and p95 latency. Commit count is the leading indicator of repository bloat.
5. Pilot on one non-critical workload, run shadow reads for two weeks, then cut over and retire dual-write.

Operational Impact

Maintenance

The package is effectively a maintained-by-courtesy project: one author, 11 stars, zero dependents, and a release cadence that tracks upstream fixes as one-line patches (v3.1.1 encoding, v3.1.2 PHP 8.4 nullable deprecation). That last one is instructive — the adapter went roughly 14 months between the 2024 and 2025 releases, and the 2026 entry exists only because PHP changed. Plan for a fork. Realistically this means vendoring the adapter, running our own CI and static analysis, and accepting that Flysystem 4 will require us to port it ourselves. Budget roughly 2–4 days per year of baseline upkeep, plus an unfunded migration whenever Flysystem makes a major move.

Support

There is no vendor and no SLA. Issues on the tracker may go unanswered. Internal ownership must be assigned to a named team before adoption; adoption without a named owner is how this becomes an orphaned dependency discovered during an incident. Escalation path is "we fix it" — which is acceptable for a ~10-class adapter but must be stated in the ADR.

Scaling

Scaling is the weakest dimension and it scales along the wrong axis. Throughput is bounded by GitLab API rate limits and by Git's own serialization of commits onto a branch, not by our application tier. Listing cost grows with repository size because tree walks paginate. Storage grows monotonically — the adapter has no meaningful delete history story, so "deleted" files persist in history and continue inflating clones forever. Concurrency is unsafe by construction. The correct scaling strategy is horizontal isolation: one project or branch per environment or tenant, with explicit size and object-count budgets and alerts when they are approached.

Failure Modes

• Rate limiting (429) under batch or burst writes — the most likely production incident. Requires backoff, jitter, and queueing, not raw synchronous calls in a request cycle.
• Commit conflicts / non-fast-forward when two workers write concurrently to one branch. Mitigate with single-writer queueing per branch; retries alone can loop.
• Token expiry or revocation causes total, immediate write failure with a 401. Needs proactive rotation and an alert on auth failures.
• Large writes timing out mid-commit, leaving ambiguity about whether the write landed. Writes must be treated as non-idempotent and verified before retry.
• Silent divergence between the bridge and the adapter if the two packages are versioned independently.
• Repository bloat as a slow-burn failure: clones and CI checkouts degrade gradually until pipelines start timing out, with no single alerting threshold crossed.

Ramp-Up

Very low for consumers — anyone who knows Laravel's Storage facade is productive in minutes, and no GitLab API knowledge is required. The real ramp-up cost sits with the platform team: understanding GitLab's Repository Files API, pagination, rate limits, token scoping, and Git's commit semantics well enough to debug a 409 or a 429 at 2am. Estimate 2–3 days of focused onboarding for the owning engineer, most of it on GitLab API behaviour rather than on this package. Onboarding documentation should be written in-house during the pilot — the README covers installation and construction, but says nothing about failure behaviour, concurrency, or size limits, which is precisely what an on-call engineer will need.