# Bug reports

Submit a bug report to the Champagne GitHub repository.

Source: https://docs.champagne.dev-ukab.fr/fr/graphql/bug-reports

Signed-in staff can use **Settings → Report a bug** to create an issue in
`ukab-labs/champagne`. Members and anonymous callers cannot submit reports.
Error toast **Report** actions open the same GitHub reporting flow with read-only
diagnostics and editable context about what the user was doing. The description
includes the error message, available masked backend message, HTTP status, GraphQL
code, request ID, timestamp and page origin/path. Query strings, URL fragments,
raw stacks, request payloads, credentials and account details are not collected.
Development reports prefer the actual Waggle trace link when a valid server trace ID is available; otherwise Compose configures a request-ID-filtered Waggle log link via
`VITE_WAGGLE_URL`, using the same host and port as its Caddy receiver. Production
reports retain the request ID and timestamp for authorized Cockpit investigation,
without assuming a trace exporter or datasource URL. Diagnostics can be reviewed
before sending. The form reminds users not to share passwords or personal data.

Members and signed-out users can continue with a prefilled GitHub issue draft,
which requires their own GitHub access and explicit submission there. This does
not grant them access to the staff-only API or expose the server's GitHub token.

GitHub draft URLs are limited to 7,000 encoded bytes. Larger drafts contain a
bounded summary with correlation information and instructions to paste the full
report before submitting. The modal offers **Copy full report** and selectable,
read-only full contents; clipboard failures remain inline. This URL limit never
truncates the description sent through the staff mutation.

```graphql
mutation ReportBug($input: BugReportInput!) {
  reportBug(input: $input) {
    url
    number
    error
  }
}
```

Pass `input.title` (1–200 characters) and `input.description` (1–10,000 characters).
Both are trimmed. Blank fields, null characters, and multiline titles are rejected
with `BAD_USER_INPUT`. Staff authentication uses the normal Authorization header.
There are no filters, sorting or pagination arguments.

Success returns the issue `url` and `number`, with `error: null`. Missing configuration,
GitHub rejection, timeouts and malformed provider responses return a safe `error`
with null issue fields. The UI preserves the draft on failure and displays the
submission error inline, avoiding recursive Report toasts. Pending submission
blocks duplicate sends and dismissal. An uncertain network result can mean GitHub created the issue: check
the repository before manually retrying. The server does not automatically retry.
Each API process limits each staff account to one attempt per minute; this limit
is in memory and resets on restart, and is not shared between replicas.

## Configuration [#configuration]

Create a fine-grained GitHub personal access token restricted to
`ukab-labs/champagne` with **Issues: read and write** permission. If required by the
organization, approve the token before use. Set `GITHUB_BUG_REPORT_TOKEN` in the
primary checkout’s ignored `.env.local` locally. New worktrees inherit this file
at creation; existing worktrees need their own copy of this setting. Restart the
API after changing it. Compose loads `.env.local` after `.env`.
For Scaleway deployment, supply the sensitive Terraform variable
`github_bug_report_token`; it is injected into the backend secret environment.
Never put the token in frontend configuration or commit it.

Without a token, the rest of the application continues to work; submission returns
an explicit configuration error. The issue destination is fixed on the server and
cannot be overridden by the caller. Repository access is required to view the
resulting issue when the repository is private.