Reporting an Issue

This page describes where each kind of report goes and how a fix travels from report to production. Use it whenever you find a bug, want to request a feature, have an idea to discuss, or need to disclose a security vulnerability.

Overview

Lumio uses a small number of dedicated surfaces so every report lands in exactly one place and can be tracked to resolution:

• GitHub Issues — code-level bug reports and concrete feature requests that benefit from sitting next to the code and pull requests.
• GitHub Discussions — open-ended ideas, questions, and RFC-style proposals that are not yet actionable work.
• GitHub Security Advisories — the only correct channel for security vulnerabilities. A vulnerability is never filed as a regular issue.

Accepted reports are triaged, labelled, and tracked internally through to a fix.

Where to report

Pick the surface that matches what you found:

What you have	Where it goes	Notes
Bug or error	GitHub Issue — bug report template	Include steps to reproduce, expected vs. actual behaviour, and the affected app.
Concrete feature request	GitHub Issue — feature request template	For a well-scoped, buildable change.
Open-ended idea, question, or design proposal	GitHub Discussions	Promising ideas are promoted to tracked work.
Security vulnerability	Private GitHub Security Advisory	See Security vulnerabilities below — never a public issue.

The two templates (.github/ISSUE_TEMPLATE/bug_report.yml and feature_request.yml) prompt for the details maintainers need. Blank issues are disabled — every report goes through one of the two templates or through Discussions. Labels (type, priority, status, scope; defined in .github/labels.yml) are applied during triage so you can follow progress on the report.

Security vulnerabilities

warning

Do not report a security vulnerability as a public issue or discussion.

Report vulnerabilities privately through a GitHub Security Advisory, following the repository's security policy (SECURITY.md). Private advisories keep the details restricted while a fix is prepared and let maintainers coordinate a release before any disclosure. If you cannot use GitHub Security Advisories, email security@lumio.vision and an advisory is opened on your behalf.

SECURITY.md also carries the response targets — acknowledgement within 2 business days, triage within 5, a remediation plan or status update within 10 — plus the in-scope surface list (every production domain, and the non-production lumio.*.staging.zaflun.dev environments) and what is out of scope (physical access, social engineering, DoS, unqualified scanner output). Reporters are credited in the published advisory unless they ask to stay anonymous.

Do not include secrets, credentials, or other users' personal data in a report — describe an exposed credential rather than pasting it.

How a fix reaches production

Fixes and features move through branches and a versioned release tag. The environment each stage maps to matches the Deployment and Installation guides:

Stage	Branch / tag	Environment
Development & integration	next	Staging
Release preview	main	Production preview
Release	version tag, e.g. api@2026.5.3	Production

The flow, end to end:

1. Branch and open a pull request into next. next is the staging integration branch and the default target for normal fixes and features. CI must be green and the change reviewed before it merges.
2. Promote to main. Once validated on staging, next is merged into main, the production-preview branch.
3. Cut a release. Publishing a GitHub Release on a tag in the {app}@{version} format (for example api@2026.5.3) triggers release-images.yml, which builds and pushes the container image. A pre-release publishes the beta channel tag; a full release publishes latest. The workflow can also be started manually via workflow_dispatch with an app selection. See Deployment for the full tag reference.

Promotion from next to main is a maintainer decision, not something a contributor's pull request does — open every pull request against next. An urgent security fix is the one case where a maintainer may land a change on main ahead of the normal next cycle.

Following updates

Track progress from the surface where you reported:

• Issues and Discussions — the thread's labels reflect its status, and GitHub notifications alert you to comments and status changes when you participate in or watch the thread.
• Security advisories — updates are shared privately with the reporter until a coordinated release.

See Contributing for local setup and pull-request conventions.