README

Turn Laravel errors into deduplicated, redacted GitHub issues that an AI coding agent (the Claude Code GitHub Action, DeepSeek dsh-superagent, or anything that reacts to an @mention) can pick up and fix with a pull request.

Log::error() / unhandled exception
  └─ github-issues log channel (Monolog handler: never throws, never recurses)
       ├─ filters: level, environment, ignored exceptions/messages, sampling
       ├─ report → fingerprint → redaction
       ├─ local counters in your cache (dedupe, cooldowns, hourly cap, circuit breaker)
       └─ GitHub: create issue · comment at milestones · reopen when it comes back

• Safe to drop into any app. Every failure inside the package is swallowed (at most written to PHP's error_log()), HTTP calls have a 5 s timeout, and creating the channel cannot fail.
• One issue per bug. User 123 not found and User 456 not found thrown from the same function are the same issue, across deploys and line shifts.
• No secrets leave the app. See Privacy.
• Agents are billed per trigger, so the mention is written once — when the issue is created.

Requirements: PHP 8.2+, Laravel 11, 12 or 13, Monolog 3. MIT licensed, no services besides GitHub. (Laravel 11 is past security support and current Composer refuses to install it by default; the package still works in existing Laravel 11 apps.)

Install

composer require taba2177/log-issues-github
php artisan vendor:publish --tag=log-issues-config   # optional

The repository is private: see Install from the private repository.

Enable (only .env changes)

LOG_STACK=single,github-issues            # the only line that changes logging
LOG_ISSUES_REPO=owner/repo                # where issues are created
LOG_ISSUES_TOKEN=github_pat_xxx           # fine-grained PAT, see below
LOG_ISSUES_MENTION=@claude                # or the agent's GitHub login, or empty

The package registers the github-issues channel itself — no edits to config/logging.php (an existing channel with that name is left alone). Laravel's default stack channel reads LOG_STACK, so errors keep going to storage/logs/laravel.log and to GitHub.

By default only production and staging report (LOG_ISSUES_ENVIRONMENTS). Check everything with:

php artisan log-issues:test --dry-run    # validates config, checks read access, prints a sample issue
php artisan log-issues:test              # same, then creates a real sample issue

If the target repository is public the command prints a loud warning: stack traces and file paths would be visible to everyone. Use a private repository.

Create the fine-grained token

1. GitHub → Settings → Developer settings → Personal access tokens → Fine-grained tokens → Generate new token.
2. Resource owner: the account or organisation that owns the repository.
3. Repository access: Only select repositories → pick the one repository.
4. Permissions → Repository permissions: Issues: Read and write. Metadata: Read-only is added automatically. Nothing else.
5. Pick an expiry, generate, and paste it into the server's environment as LOG_ISSUES_TOKEN. Never commit it. log-issues:test never prints it.

When the token expires, GitHub answers 401; the package keeps counting locally, opens its circuit breaker for 15 minutes at a time and shows the error in php artisan log-issues:status.

Pair with an AI agent

Every new issue ends with an Agent brief (configurable) that starts with the mention:

@claude Please investigate this production error. Find the root cause, add a failing test that reproduces it, fix it with the smallest safe change, and open a pull request that references this issue. Do not change .env, migrations that drop data, or payment code without asking in this issue first.

LOG_ISSUES_MENTION_ON controls when the mention is written:

Regular "seen N more times" comments and the automatic reopen comment never mention anyone. Use LOG_ISSUES_ON_CLOSED=new if a regression should create a fresh issue (and trigger the agent again).

Claude Code GitHub Action (@claude)

1. In the target repository install the Claude GitHub app and add the workflow — the quickest way is /install-github-app inside Claude Code. With a Claude subscription, create a token with claude setup-token and store it as the repository secret CLAUDE_CODE_OAUTH_TOKEN.

2. Make sure the workflow also runs on new issues, not only comments:

   # .github/workflows/claude.yml
   name: Claude
   on:
     issues:
       types: [opened]
     issue_comment:
       types: [created]
   jobs:
     claude:
       if: |
         (github.event_name == 'issues' && contains(github.event.issue.body, '@claude')) ||
         (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude'))
       runs-on: ubuntu-latest
       permissions:
         contents: write
         pull-requests: write
         issues: write
         id-token: write
       steps:
         - uses: actions/checkout@v4
         - uses: anthropics/claude-code-action@v1
           with:
             claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}

3. LOG_ISSUES_MENTION=@claude.

Issues are created with your PAT (not GITHUB_TOKEN), so they do trigger workflows, and the action sees an author with write access.

DeepSeek dsh-superagent (or any other agent)

1. LOG_ISSUES_MENTION=@<agent-github-login> — the login the agent listens for.

2. Add the account that owns LOG_ISSUES_TOKEN to the agent's allowed users / trusted authors list, otherwise it ignores issues opened by that account.

3. Adjust the brief to the agent's conventions if needed:

   LOG_ISSUES_AGENT_BRIEF="{mention} /fix — root-cause {title} in {repo}, add a regression test, open a PR."

   Placeholders: {mention}, {repo}, {environment}, {level}, {fingerprint}, {title}. A Blade string also works (in the published config): 'agent_brief' => '{{ $mention }} @if($environment === "production")URGENT: @endif please fix {{ $title }}'.

What an issue looks like

• Title (≤ 120 chars): [production] QueryException: SQLSTATE[23000]: Integrity constraint … (app/Services/OrderService.php:88)
• Labels: bug, auto-reported, env:production, severity:error
• Body: summary table (environment, level, first/last seen, occurrences, release, PHP/Laravel, route + method, console command, queue job, authenticated yes/no), the redacted message and the chain of previous exceptions, application frames with links to https://github.com/{repo}/blob/{sha|branch}/{path}#L{line}, collapsed vendor frames, the redacted log context, the agent brief and a hidden marker <!-- log-issues:fp=<sha1> -->.

The link ref is LOG_ISSUES_RELEASE / APP_RELEASE when it is a commit SHA, else the SHA in .git/HEAD when readable, else LOG_ISSUES_BRANCH (default main). In Docker builds without .git, set APP_RELEASE to the commit SHA at build time to get exact links.

How deduplication and noise control work

Counters live in your cache for 30 days. A cache flush only costs one search request per error.

Delivery

The job never throws, so a worker never logs a failure back into the package.

Commands

php artisan log-issues:test [--dry-run]
php artisan log-issues:scan [path=storage/logs/laravel.log] [--since=24h] [--dry-run]
php artisan log-issues:status [--reset]

• scan parses Laravel log files (single and daily laravel-YYYY-MM-DD.log, multi-line stack traces, previous exceptions), groups entries by fingerprint and reports them through the same pipeline — useful for the first rollout and for apps that cannot change LOG_STACK. path may be a file, a directory or a glob. The byte offset per file is remembered, so it can run from the scheduler:

  // routes/console.php
  Schedule::command('log-issues:scan --since=2h')->hourly()->withoutOverlapping();

• status lists fingerprints with counts, first/last seen and issue numbers, the circuit breaker, the hourly cap and the last GitHub error. --reset closes the circuit breaker.

Configuration

All keys live in config/log-issues.php; most have an env variable:

Privacy

Redaction is always on and runs before anything is queued or sent:

• Never collected: request bodies, headers, cookies, session data, the authenticated user's identity (only authenticated: yes/no, without loading a user), URLs with their query strings.
• Masked in messages, previous exceptions and context: e-mail addresses, phone numbers, Luhn-valid card numbers, IBANs, JWTs, Bearer/Basic credentials, GitHub/OpenAI/Slack/AWS key shapes, password=…-style pairs, URL query strings, the literal values of APP_KEY, every database / redis / mail password and the package's own token.
• Masked by key at any depth of the context: password, passwd, pwd, secret, token, api_key, authorization, cookie, session, credential, private_key, user_id/userId, email, phone, credit_card, card_number, cvv, iban, ssn (+ redact.keys).
• Long strings are truncated, deep or wide arrays are cut, objects become [object Class].

Add your own rules with redact.keys and redact.patterns. Still: report into a private repository and review what a sample issue contains (log-issues:test --dry-run).

Troubleshooting

Development

composer test        # Pest + Testbench, Http::fake() only, no network
composer analyse     # PHPStan (Larastan) level 8
vendor/bin/pint --test

Integrate into laravel-project

1. In laravel-project/composer.json add the private VCS repository:

   "repositories": [
       { "type": "vcs", "url": "https://github.com/taba2177/log-issues-github" }
   ]

2. Require it (Composer needs read access to the private package repository — composer config --global github-oauth.github.com <token> locally; in the Dokploy build, a COMPOSER_AUTH={"github-oauth":{"github.com":"<token>"}} build-time environment variable with a token that has Contents: read on taba2177/log-issues-github):

   composer require taba2177/log-issues-github:^0.1

3. In Dokploy → laravel-project → Environment add:

   LOG_STACK=single,github-issues
   LOG_ISSUES_REPO=taba2177/laravel-project
   LOG_ISSUES_TOKEN=github_pat_xxx
   LOG_ISSUES_MENTION=@claude

4. Redeploy, then run php artisan log-issues:test --dry-run in the container, followed by php artisan log-issues:test once to see a real sample issue. Optionally backfill with php artisan log-issues:scan --since=24h --dry-run first.

License

MIT — see LICENSE.