README

Create issues for Exceptions that happen on your servers.

This package will create issues in your Gitlab project if Exceptions occur and will post some more debug information to the issue to help you solve problems.

This package will contact your Gitlab server and checks if an exception has occurred before based on a generated identifier hash in the issue description. Don't remove this line in the description as it will be the only way for this package to validate if an exception occurred before.

Gitlab version 9 or higher required.

Installation

Install with composer

composer require wyox/laravel-gitlab-reporter

This package supports Laravel 12 and 13 (PHP 8.2 or higher).

To use the Gitlab reporter, open your bootstrap/app.php and add the code shown below between the comments to the withExceptions closure

    ->withExceptions(function (Exceptions $exceptions) {
        // ADD below
        $exceptions->report(function(\Throwable $e){
            if (app()->bound('gitlab.report')) {
                app('gitlab.report')->report($e);
            }
        });
        // ADD Above
    })

Now setup your .env file to include the following variables:

GITLAB_REPORT_URL=https://gitlab.com/
GITLAB_REPORT_TOKEN=
GITLAB_REPORT_PROJECT_ID=
GITLAB_REPORT_LABELS=
GITLAB_USE_CACHE=true

I would suggest making a separate user account for the reporter and only let it access Issues and allow it for issue creation. This way you can ensure if your server or code gets compromised you won't give full access to the server

To retrieve an access token go to your gitlab server to profile/personal_access_tokens and generate a token for using the API

For your Project ID you need to go to your project -> Settings -> General -> General Project settings. There should be a box with Project ID

Adding labels to issues

Adding labels to newly created issues is easy, just add a comma-separated list to GITLAB_REPORT_LABELS=

GITLAB_REPORT_LABELS=bug,critical

If the labels don't exist in Gitlab they will be automatically created.

Ignoring certain exceptions

Make sure you publish the config as setting exceptions is not possible using an .env file

php artisan vendor:publish --tag=gitlab-report

A file called gitlab-report.php will be created there and you can change settings there. A couple of exceptions have been added by default

Hiding fields in reports

In some cases you don't want reports to contain passwords of your clients. You can extend or replace values in the configuration file to include more fields that shouldn't show up in a report. All these fields will be replaced with [redacted]. Matching is case-insensitive, so Authorization and authorization are both redacted. A set of common sensitive field names (passwords, tokens, secrets, api keys, authorization, etc.) is redacted by default.

What's in a report

Each issue description is built from a number of sections:

• Exception summary - type, message, file/line and (for HTTP) the request method, URL and authentication state.
• Context - environment, Laravel/PHP version, host, timestamp and (for HTTP) client IP and user agent.
• Code - a source excerpt around the line that threw the exception.
• SQL - the failing query (only for QueryException).
• Query params / POST / Session / User - sanitized request data (HTTP only).
• Trace - the stack trace, followed by a Caused by section for every previous exception in the chain.

Duplicate issues and recurrences

Exceptions are deduplicated using a hash of the request/command, exception class and a normalized message (dynamic ids, UUIDs and hashes are masked) plus the file and line. When an open issue already exists for an exception, a throttled "occurred again" note is added to it instead of creating a duplicate. The throttling window is shared with the local cache (GITLAB_USE_CACHE).