Flysystem Gitlab Storage Laravel Package

Product Decisions This Supports

1. Build-vs-buy for "GitLab-native artifact storage" — a narrow but real niche. This package is a candidate answer to one specific user story: "our build outputs, exports, or versioned docs must live inside the GitLab project they belong to." It is not a general-purpose storage layer, and treating it as one is the primary way this decision goes wrong. The PM value of the package is that it makes a Git-backed content store cheap to prototype (a Composer require plus a disk config entry), which converts an expensive "should we build a GitLab integration?" debate into a one-week spike. That is the real ROI: de-risking a roadmap question, not shipping production infrastructure.

2. Roadmap scoping: it defines the boundary of a "versioned artifacts" feature. Because every write() is a commit and directories are emulated with .gitkeep files, the package implicitly documents the envelope of what the feature can claim. Useful for scoping:

• Append-only, low-churn content — changelog snapshots, generated reports, exported CSVs, documentation bundles, per-release fixtures.
• Human-auditable history as a feature: "who changed this file, when, and why" comes free from Git, which is genuinely hard to replicate with S3 and is a legitimately differentiating pitch for compliance-adjacent customers.
• Explicitly out of scope: user-uploaded media at volume, session/cache data, anything with high write frequency or multi-MB objects.

If the roadmap item is "let customers attach files to projects," this package is the wrong foundation and the decision should be recorded as such before an engineer spends a sprint on it.

3. Self-hosted / data-residency positioning. The configurable base URL and PAT authentication mean the same adapter serves gitlab.com and an air-gapped self-hosted instance. That supports a product decision that is otherwise awkward: offering an "on-prem-compatible" storage option without building a bespoke connector. For teams selling into regulated or enterprise accounts, that can be a cheap checkbox on an RFP response — but pair it with the honest caveat that a Git-backed store is not a substitute for object storage in an enterprise architecture review.

4. Pricing and packaging input — small, but not zero. If GitLab project storage is the retention surface, then retention, quota, and cleanup become product surface area: repository growth affects customer clone times, CI duration, and GitLab's own storage billing. A PM should decide whether the feature is included (accepting repo bloat as a cost of the feature) or metered (per-project artifact size limits). This package gives you no quota enforcement — that becomes your engineering work if you ship it.

5. Dependency posture decision: pin, vendor, or reject. 11 stars, 0 dependents, a single maintainer, and a first release in 2019 with mostly maintenance-only changelog entries (the last two releases are a rawurlencode() path fix and a PHP 8.4 nullable deprecation fix). That is a low-signal, low-velocity dependency. The PM decision isn't "good or bad package" — it's "do we accept ownership of a fork?" Making that call explicitly, early, is cheaper than discovering it during an incident. A reasonable default: adopt behind an interface with a vendor-fork escape hatch, and treat the Laravel bridge as optional (a service-provider driver is roughly a day of work, per engineering).

6. Kill-criteria definition. A PM can pre-commit the conditions under which the feature is abandoned or re-platformed: sustained write volume above a low threshold, repo size crossing a clone-time budget, rate-limit retries exceeding an acceptable error budget, or the maintainer going dark for N months. Written down in advance, these prevent a sunk-cost argument later.

When to Consider This Package

Consider it when all of these hold:

• The requirement is genuinely "files must live in GitLab, in a specific project and branch." If the actual requirement is "files must not leave our infrastructure," MinIO or any S3-compatible store wins on every axis — cheaper, faster, purpose-built, and better supported.
• Write volume is low and predictable: hundreds to low thousands of objects over a year, not thousands per day.
• Files are small — think kilobytes to low single-digit megabytes. Assume large files land in the repository proper; the README and changelog describe the Repository Files API only, with no LFS endpoints. Verify before promising anything about big files.
• Git history is a feature you are selling (auditability, rollback, diffability), not incidental overhead.
• You are on PHP 8.1+ and Flysystem 3 (Laravel 9+). Anything older requires pinning adapter 2.0.4 or 1.1.0 — decline that; it is a compounding liability.
• You pin ^3.1.1 at minimum, because the earlier urlencode() behaviour breaks paths containing spaces on current GitLab versions — a customer-visible bug if filenames are user-influenced. Add a round-trip test for spaces and non-ASCII.
• Someone owns PAT lifecycle: scoping to a service account, rotation cadence, revocation runbook. This is a broad credential; treat it as a security workstream, not a config value.
• You accept concurrency reality: no file locking, last-write-wins, retry-and-reconcile rather than transactional semantics.

Look elsewhere when:

• You need an object store: user uploads, media pipelines, CDN-backed assets, session or cache data.
• You need high write throughput, low-latency writes, or read-after-write guarantees under concurrency. A commit-per-write model will not give you transactional behaviour.
• You need to store large files without bloating a repo that every developer clones and every CI pipeline checks out.
• You cannot tolerate a single-maintainer dependency without community backstop, or you have no capacity to fork. In that case the honest options are: build a thin internal adapter (~a day of driver work) or select a vendor-backed backend.
• Your GitLab version matrix is uncertain and you cannot validate API v4 and pagination behaviour against the self-hosted instances your customers actually run.
• You wanted a drop-in Laravel disk driver. Note that the bridge is a separate package, royvoetman/laravel-gitlab-storage; verify it supports Flysystem 3 and your Laravel version before treating it as a blocker-free install.

Verdict framing: viable for a scoped spike or a narrow internal tool; not viable as a strategic storage backend without an explicit fork-and-own commitment.

How to Pitch It (Stakeholders)

To executives (one paragraph): "We have a recurring request to keep generated files inside customers' GitLab projects, with a full audit trail of who changed what. Rather than fund a bespoke integration, an open-source adapter lets us validate the demand in about a week at near-zero cost, using the same storage interfaces we already use elsewhere so nothing in the application needs rewriting if we later change backends. The technology is small and maintained by one person, so I'm recommending a time-boxed spike with a written exit plan — not a production commitment. If the spike shows write volumes are modest, this could become a differentiated 'everything stays in your Git and never leaves your infrastructure' story for enterprise buyers."

To engineering:

• Install is one Composer package; the Laravel disk driver is a separate package you should evaluate but treat as replaceable — a Storage::extend() service provider is about a day of work.
• Consumption stays behind Storage, so application and domain code never learn GitLab exists. The adapter is the seam.
• Constraints to confirm at install: PHP 8.1+, Flysystem ^3, GitLab API v4, ^3.1.1 pinned for the rawurlencode() fix.
• The spike must answer: actual commit volume and repo growth, rate-limit behaviour under batch writes, whether copy/move are native or read-then-write, streamed-read memory profile, and failure handling for 401/403/404/429/5xx without duplicating writes.
• Security: PAT scoped to a service account, stored in the secrets manager, rotation documented.
• Plan for the dependency to be forked and vendored; pin versions and avoid relying on the maintainer for fixes.

To security and platform teams: One credential class, one blast radius, one runbook. The token can write repository contents, so scope it narrowly, rotate it on schedule, and log its use. Repo-growth impact on developer clones and CI duration is a platform cost the feature must budget for, not an implementation detail.

Ask: approve a one-week spike, two days of driver validation, and a written kill-criteria list (volume ceiling, repo-size budget, rate-limit error budget, maintainer-inactivity threshold) agreed before work starts.