GitHub integration

Connecting a project to its GitHub repository lets Quiet Guard follow the work that ships your app and correlate production errors back to the commit that introduced them.

On the paid plans. The GitHub integration is part of Indie and Studio. On Free the project's Settings page shows what the integration does instead of the repository fields. Everything already synchronised stays visible on the project's GitHub tab; nothing new is fetched while the plan does not include it.

Connect a repository

On the project's Settings page, section GitHub integration, fill in:

• Repository: the repository in owner/name form (e.g. acme/store), exactly as it reads in the GitHub URL.
• Access token: a GitHub personal access token that can read that repository. Quiet Guard only ever reads three things: the repository's metadata, its commits and branches, and its pull requests. It never writes, except to open an issue from an anomaly when you allow it (see below).

Create the token on GitHub

1. Signed in to GitHub with an account that can see the repository, open Settings > Developer settings > Personal access tokens > Fine-grained tokens, then Generate new token. Direct address: https://github.com/settings/personal-access-tokens/new.
2. Resource owner: the user or organisation that owns the repository. For an organisation's repository, choose the organisation, not your own account; some organisations require an administrator to approve the token before it works.
3. Repository access: Only select repositories, then the one repository.
4. Repository permissions: Contents in Read-only (commits and branches) and Pull requests in Read-only. GitHub adds Metadata in Read-only by itself. To follow the repository's issues, add Issues in Read-only; to open one from an anomaly, Issues in Read and write. Nothing else.
5. Expiration: whatever your policy allows. When the token expires, synchronisation stops and nothing new appears in the GitHub tab until you paste a new one.
6. Generate the token and copy it (it starts with github_pat_): GitHub shows it once.

Paste it in the Access token field and save. The field never shows the stored token again: leave it blank on later saves to keep the current one, type a new one to replace it.

A classic personal access token works too, with the repo scope for a private repository or public_repo for a public one. The fine-grained kind is preferred: it can be limited to one repository and to read-only permissions, which is all this integration uses.

The token is encrypted at rest. The github_token column is stored using Laravel's encrypted cast, so the token is never persisted in clear in the database.

A project is considered GitHub-connected once both a repository and a token are present. Run Sync GitHub once right after saving: it is the quickest way to find out a token does not open the repository.

What gets synced

Syncing fetches and stores three kinds of repository activity, and a fourth on request:

• Commits: recent commits, with SHA, message, author and timestamp.
• Pull requests: open and recent PRs.
• Branches: the repository's branches, reconciled on each sync (branches that disappeared upstream are removed locally).
• Issues, when the project asked for them: the repository's issues, their labels and, optionally, their comments (see The repository's issues).

Syncing follows a fetch-all-then-write-in-a-transaction approach: data is pulled from the GitHub REST API first and written in one transaction, so a partial network failure never leaves the project with a half-updated picture.

Run a sync

Use the Sync GitHub action on the GitHub tab (under the project's Settings menu) to pull the latest activity on demand. The synced commits, PRs and branches are shown in the project's GitHub tab.

On the plans that carry the integration, a connected project is also synced on its own, a few times a day, so the picture stays current between two deploys without anyone clicking.

The repository's issues

GitHub issues are the team's conversation: pulling them into the dashboard is a choice, not a side effect of the token pasted for the commits. On the project's Settings page, GitHub integration section, four switches, all off by default:

• Follow the repository's issues: on every sync, the repository's open issues land on the project's GitHub tab, under Issues, with their title, author, labels and comment count. The pull requests GitHub lists among the issues are dropped, they have their own tab.
• Fetch the comments too: one GitHub request per commented issue, limited to the thirty most recently updated issues on each sync. A comment deleted on GitHub disappears at the next sync.
• Include closed issues: without it, the tab lists open issues only. Closed ones stay synced, so an issue tied to an anomaly says when it closes. A sync reads the repository's 100 most recently updated issues.
• Open a GitHub issue for every new anomaly: see below.

From the tab, Read opens an issue and its comments without leaving the dashboard; the Markdown is rendered by the same engine as this documentation, which escapes everything before showing it. Open on GitHub leads to the issue itself. The token needs the Issues permission in read-only.

From an anomaly

On an anomaly's page, two actions appear as soon as the project follows its repository's issues:

• Open a GitHub issue proposes a title and a description composed from the anomaly's metadata: the exception class, the location, the first frame in your code, the number of occurrences, the environments and releases touched, and the link back to the dashboard. The exception message is included only while it is not encrypted: a team that seals its content never has it copied to GitHub by this action. Read and edit before sending, the text is public if the repository is. The issue is created with the quiet-guard label and tied to the anomaly, which then shows it in its overview.
• Link a GitHub issue ties the anomaly to an open issue already synced, for a report somebody wrote before you.

The project's Issues tab shows, for each issue, the anomaly it tracks.

With Open a GitHub issue for every new anomaly, the first occurrence of a never-seen exception opens the issue by itself, with the same body, nobody clicking. A regression (a resolved anomaly happening again) opens no new one: the issue it had is still there. A refusal from GitHub (a token without the write permission, an archived repository) is logged and never stops the ingestion; the issue can then be opened by hand. At most ten issues an hour per project are opened this way: a leaked project key can manufacture anomalies at will, and it must not fill your repository under your name.

Opening an issue needs the Issues permission in Read and write on the token; it is the only write the integration ever makes on your repository.

Release → commit correlation

This is where the GitHub data pays off. When an exception occurrence carries a release value that is a commit SHA, Quiet Guard resolves it to the matching synced commit. From the issue you can open the exact commit that was deployed when the error happened.

The same commit serves the stack trace: on an anomaly's page, every frame of your application offers Open this file on GitHub, at the exact line, in the commit that was deployed when the occurrence fired (failing that, on the repository's default branch).

For this to resolve, two things must line up:

1. Your app sends the deployed commit SHA as context.release in the exception payload.
2. That commit has been synced from GitHub.

Tip: the Laravel SDK detects the SHA by itself from the checkout or a REVISION file, and the configuration page gives one recipe per deployment shape (Forge, Envoyer, GitHub Actions, Docker). Then run a GitHub sync after each deploy, so the error → commit link is always available.