- What is royvoetman/flysystem-gitlab-storage used for?
- It is a Flysystem adapter that stores and manages files in a GitLab repository through the Repository Files API v4. In Laravel, it lets the Storage facade use a GitLab-backed disk without application code knowing about GitLab. It fits low-churn, version-controlled artifacts rather than high-volume object storage.
- How do I install and configure the GitLab Flysystem adapter in Laravel?
- Install the adapter with composer require royvoetman/flysystem-gitlab-storage. For Laravel disk integration, use the separate royvoetman/laravel-gitlab-storage package and configure project ID, branch, base URL, personal access token, and optional path prefix in config/filesystems.php. All values can come from environment variables, and the branch acts like the bucket for isolation.
- Which Laravel and Flysystem versions does this package support?
- Current adapter releases target Flysystem 3, which is the line that aligns with Laravel 9 and newer. Flysystem 1 and 2 users must pin older adapter versions such as 1.1.0 or 2.0.4. Check the Laravel bridge constraints before committing, because the bridge is a separate package and may lag behind.
- Do I need a personal access token for a private GitLab project?
- Yes. Private projects require a GitLab personal access token that can access the Repository Files API. Store the token in a secrets manager or environment variable, scope it to a service account with least privilege, and plan rotation. Public projects may not need the same authentication level, but the adapter constructor still takes a token argument.
- Can I use this adapter for user uploads or high-write application storage?
- Generally no. Every write becomes a commit on the configured branch, so high-frequency writes, sessions, and volume user uploads will bloat the repository and slow clones and CI. Use it for low-churn, version-controlled artifacts instead. If you need object storage semantics, use S3-compatible storage such as MinIO.
- How does the adapter handle directories and folder creation?
- GitLab's Repository Files API is Git-backed and does not have real directories. The adapter emulates directory creation with .gitkeep files according to its changelog. Listings are paginated tree walks, so deep or large directory structures can be slower than an object store.
- Does royvoetman/flysystem-gitlab-storage support GitLab LFS for large files?
- LFS support is not documented in the README or changelog; they describe Repository Files API usage only. Until you verify it explicitly, assume large files are committed into the repository proper. That makes LFS a question to test before relying on this adapter for multi-megabyte assets.
- What are the main production risks of using GitLab as a filesystem backend?
- Key risks include repository bloat from commit-per-write behavior, broad personal access token scope, API rate limiting, and concurrent write conflicts without file locking. The package is also single-maintainer with a small community, so plan to vendor or fork and pin it. Batch writes, cache listings, and add retry logic with exponential backoff.
- How should I test a Laravel app that uses the GitLab storage disk?
- The package does not advertise a dedicated testing fake, so keep application tests isolated from the real GitLab API. Use Flysystem's in-memory adapter or mock the GitLab HTTP client for adapter-level tests, and reserve a disposable GitLab project for integration checks. Avoid pointing CI at a shared production branch.
- What alternatives should I consider before choosing a GitLab Flysystem adapter?
- If the real requirement is keeping files inside your infrastructure, S3-compatible storage such as MinIO avoids repository-as-storage tradeoffs. If you need GitLab specifically, compare the separate Laravel bridge against writing a small Storage::extend driver around the adapter. Also consider whether version-controlled artifacts belong in Git or in an artifact registry.