README

Automatically create GitHub issues from your Laravel exceptions & logs. Perfect for smaller projects without the need for full-featured logging services.

Requirements

PHP ^8.3
Laravel ^11.0
Monolog ^3.6

Features

✨ Automatically create GitHub issues from Exceptions & Logs
🔍 Group similar errors into single issues
💬 Add comments to existing issues for recurring errors
🏷️ Support customizable labels
🎯 Smart deduplication to prevent issue spam
⚡️ Buffered logging for better performance

Showcase

When an error occurs in your application, a GitHub issue is automatically created with comprehensive error information and stack trace:

The issue appears in your repository with all the detailed information about the error:

If the same error occurs again, instead of creating a duplicate, a new comment is automatically added to track the occurrence:

Installation

Install with Composer:

composer require naoray/laravel-github-monolog

Configuration

Add the GitHub logging channel to config/logging.php:

'channels' => [
    // ... other channels ...

    'github' => [
        // Required configuration
        'driver' => 'custom',
        'via' => \Naoray\LaravelGithubMonolog\GithubIssueHandlerFactory::class,
        'repo' => env('GITHUB_REPO'),    // Format: "username/repository"
        'token' => env('GITHUB_TOKEN'),  // Your GitHub Personal Access Token

        // Optional configuration
        'level' => env('LOG_LEVEL', 'error'),
        'labels' => ['bug'],
    ],
]

Add these variables to your .env file:

GITHUB_REPO=username/repository
GITHUB_TOKEN=your-github-personal-access-token

You can use the github log channel as your default LOG_CHANNEL or add it as part of your stack in LOG_STACK.

Getting a GitHub Token

To obtain a Personal Access Token:

Go to Generate a new token (this link pre-selects the required scopes)
Review the pre-selected scopes (the repo scope should be checked)
Click "Generate token"
Copy the token immediately (you won't be able to access it again after leaving the page)
Add it to your .env file as GITHUB_TOKEN

Note: The token requires the repo scope to create issues in both public and private repositories.

Usage

Whenever an exception is thrown it will be logged as an issue to your repository.

You can also use it like any other Laravel logging channel:

// Single channel
Log::channel('github')->error('Something went wrong!');

// Or as part of a stack
Log::stack(['daily', 'github'])->error('Something went wrong!');

Advanced Configuration

Deduplication and buffering are enabled by default to enhance logging. Customize these features to suit your needs.

Deduplication

Group similar errors to avoid duplicate issues. By default, the package uses file-based storage. Customize the storage and time window to fit your application.

'github' => [
    // ... basic config from above ...
    'deduplication' => [
        'store' => 'file',  // Default store
        'time' => 60,       // Time window in seconds
    ],
]

Alternative Storage Options

Consider other storage options in these Laravel-specific scenarios:

Redis Store: Use when:
- Running async queue jobs (file storage won't work across processes)
- Using Laravel Horizon for queue management
- Running multiple application instances behind a load balancer
```
'deduplication' => [
    'store' => 'redis',
    'prefix' => 'github-monolog:',
    'connection' => 'default',  // Uses your Laravel Redis connection
],
```

Database Store: Use when:

Running queue jobs but Redis isn't available
Need to persist deduplication data across deployments
Want to query/debug deduplication history via database

'deduplication' => [
    'store' => 'database',
    'table' => 'github_monolog_deduplication',
    'connection' => null,  // Uses your default database connection
],

Buffering

Buffer logs to reduce GitHub API calls. Customize the buffer size and overflow behavior to optimize performance:

'github' => [
    // ... basic config from above ...
    'buffer' => [
        'limit' => 0,        // Maximum records in buffer (0 = unlimited, flush on shutdown)
        'flush_on_overflow' => true,  // When limit is reached: true = flush all, false = remove oldest
    ],
]

When buffering is active:

Logs are collected in memory until flushed
Buffer is automatically flushed on application shutdown
When limit is reached:
- With flush_on_overflow = true: All records are flushed
- With flush_on_overflow = false: Only the oldest record is removed

Signature Generator

Control how errors are grouped by customizing the signature generator. By default, the package uses a generator that creates signatures based on exception details or log message content.

'github' => [
    // ... basic config from above ...
    'signature_generator' => \Naoray\LaravelGithubMonolog\Deduplication\DefaultSignatureGenerator::class,
]

You can implement your own signature generator by implementing the SignatureGeneratorInterface:

use Monolog\LogRecord;
use Naoray\LaravelGithubMonolog\Deduplication\SignatureGeneratorInterface;

class CustomSignatureGenerator implements SignatureGeneratorInterface
{
    public function generate(LogRecord $record): string
    {
        // Your custom logic to generate a signature
        return md5($record->message);
    }
}

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

The MIT License (MIT). Please see License File for more information.

naoray / laravel-github-monolog

Maintainers

Details