- How do I use this package to store Laravel CI/CD artifacts in a GitLab repo?
- Install the package via Composer, configure a GitLab client with your project ID, branch, and access token, then create a Flysystem adapter. Use the Storage facade (or FilesystemOperator) to upload/download files directly to your GitLab repo. Example: `Storage::disk('gitlab')->put('artifacts/build.log', $fileContents)`.
- Does this work with GitLab self-managed instances or only GitLab.com?
- This package works with both GitLab.com and self-managed instances. Just replace the base URL in the client configuration with your instance’s domain (e.g., `https://gitlab.example.com`). Ensure your GitLab version supports API v4, which most modern instances do.
- What Laravel versions are officially supported?
- The package is tested and compatible with Laravel 10.x and 11.x. It leverages Flysystem 2.x, which aligns with Laravel’s latest ecosystem. For older Laravel versions (e.g., 9.x), ensure you’re using a compatible Flysystem version (check the package’s branch tags).
- How do I handle files with spaces or special characters in paths (e.g., 'my folder/file.txt')?
- The package now fixes a critical bug in v3.1.1: it uses `rawurlencode()` instead of `urlencode()` for paths, resolving 400 Bad Request errors for files with spaces or special characters. No manual configuration is needed—the fix is automatic. Test edge cases like `my folder/file.txt` or `file%20with%20spaces.txt` in your CI/CD pipelines.
- Can I use this for large files (e.g., >10MB) or should I stick with GitLab LFS?
- For files larger than 10MB, GitLab LFS (Large File Storage) is still the recommended approach. This package is optimized for smaller files, configs, or CI/CD artifacts. If you need to handle large binaries, combine this adapter with GitLab LFS or a dedicated object storage like S3.
- How do I configure this in Laravel’s `filesystems.php` for seamless integration?
- Add a new disk entry in `config/filesystems.php` under the `disks` array. Use the `gitlab` driver and specify the client configuration (project ID, branch, base URL, and token). Example: `'gitlab' => ['driver' => 'gitlab', 'client' => ['project_id' => env('GITLAB_PROJECT_ID'), 'branch' => 'main', 'base_url' => env('GITLAB_URL'), 'token' => env('GITLAB_TOKEN')]]`.
- What’s the best way to authenticate with GitLab for private projects?
- Use a GitLab Personal Access Token with the `api` scope. Store the token securely in your `.env` file (e.g., `GITLAB_TOKEN=your_token_here`). Rotate tokens periodically and restrict permissions to minimize risk. For CI/CD, use GitLab’s built-in CI variables or masked secrets.
- Will this work with spatie/laravel-medialibrary for managing images?
- Yes, this package is fully compatible with `spatie/laravel-medialibrary`. Configure the medialibrary to use the `gitlab` disk in its `config/medialibrary.php`, and it will seamlessly upload/download images to your GitLab repo. No additional setup is required beyond the standard medialibrary configuration.
- How do I handle concurrent file writes or conflicts in a shared GitLab branch?
- Concurrent writes can cause conflicts if multiple processes or users upload files to the same path. To mitigate this, use branch-specific paths (e.g., `ci-artifacts/v1.0/`) or implement a locking mechanism. GitLab’s API will overwrite files by default, so design your workflow to avoid race conditions.
- Are there any performance considerations for frequent API calls to GitLab?
- The package includes exponential backoff for rate limits and token caching to reduce API calls. For high-frequency operations, consider batching uploads or using GitLab’s webhooks to trigger syncs. Monitor API errors in your logs, especially if you’re hitting GitLab’s rate limits (typically 60 requests per minute for personal access tokens).