Connect GitHub
Connecting GitHub gives Guidely your commits, so it can:
- list the commits and authors of each release, and the files they changed;
- show suspect commits and
git blamefor the line an error happened on; - resolve issues when a commit that says
Fixes NORTHWIND-42ships in a release; - open and link GitHub Issues from errors, recordings, conversations and complaints.
One connection serves the whole Guidely workspace; each project then links the repositories it's built from.
There are two ways to connect. Use your own Guidely GitHub App unless you're on GitHub Enterprise Server.
| Your Guidely GitHub App (recommended) | Personal access token | |
|---|---|---|
| Who owns it | Your GitHub organization: Guidely creates the app there for you, private to it | A GitHub user (ideally a bot account) |
| Credentials | None to manage: Guidely keeps the app's keys encrypted and uses short-lived tokens | A token you create, store in Guidely and rotate yourself |
| Repositories | The ones you grant on GitHub, kept in sync automatically | The ones you pick in Guidely |
| New commits | Arrive as they're pushed | Fetched when a release names them |
| Issues closed on GitHub | Shown on the linked ticket and in the issue's activity at once; closed as completed resolves the error | Checked every ~10 minutes, same result |
| GitHub Enterprise Server | No | Yes |
1. Create the Guidely GitHub App
A Guidely workspace admin opens Integrations → GitHub in any project and clicks Create the Guidely GitHub App.
- Pick where to create it: your GitHub organization (type its name, as in
github.com/your-org; you need to be an owner or app manager of it) or your personal account. - Keep the suggested name, Guidely (your-org), or change it. It must include "Guidely" and app names are unique across GitHub: if GitHub says the name is taken, change it on GitHub's page (for example Guidely for your-org).
- Click Continue on GitHub. GitHub shows the app with everything filled in: click Create GitHub App.
The app belongs to your organization and is private to it: only your organization can install it. Guidely stores its keys encrypted; nobody at Guidely needs to set anything up.
2. Install it
GitHub goes straight on to the app's install page.
- Choose All repositories or Only select repositories. Guidely only ever sees the repositories you choose here; you can change it later.
- Click Install & Authorize. GitHub asks you to authorize the app too: this lets Guidely check that your GitHub account really can access the installation you just made.
GitHub sends you back to Guidely, which shows the organization, the repository access and the repositories.
Not an owner of the organization? GitHub lets you request the installation instead. Guidely shows Waiting for approval until an owner approves it on GitHub; then click Finish connecting. If someone installs the app directly on GitHub, Guidely notices and shows Finish connecting too.
Optional: give it the Guidely logo. GitHub doesn't let Guidely set a logo when creating the app. The GitHub card offers Download the logo and a link to the app's settings: upload it under Display information.
3. Link repositories to each project
Under Integrations → GitHub → Repositories of this project, click Link repository, pick it and set its path mapping, so stack frames point at files in the repository (for example app:/// → nothing, or /srv/app/ → backend/). Path mapping explains the options. Linking needs the Developer settings permission.
4. Tell Guidely about releases
Send the commits of each release from CI, with the Guidely CLI or sentry-cli releases set-commits, as Releases describes. With the GitHub App, commits pushed to linked repositories are already in Guidely, with the files they changed, by the time the release names them.
Managing the connection
| To | Do |
|---|---|
| Add or remove repositories | Repository access (the installation's settings on GitHub). Guidely follows within seconds; Refresh reads them again right away. A removed repository keeps its project links and commits, marked not fetched. |
| Pause it | Turn Enabled off. Nothing is fetched until you turn it back on. |
| Disconnect | The trash icon. Guidely deletes the app's stored keys and the connection, then links you to the app on GitHub, where you delete it (Advanced → Delete GitHub App). You can create a new one afterwards. |
| Move from a token to the app | Switch to a GitHub App: create and install it as above. The token is deleted; repositories and their project links stay. |
If an owner suspends or uninstalls the app on GitHub, the card says so and commits aren't fetched until it's unsuspended or installed again (Install again).
Using a personal access token instead
For GitHub Enterprise Server, or when you can't create apps in your organization, click Use a personal access token instead:
- Create a fine-grained personal access token (Settings → Developer settings), ideally for a bot account, for the repositories you want, with Contents: read and Issues: read and write. Classic tokens with
repowork too. - Paste it, click Load repositories and pick the ones to add.
The token is stored encrypted and never shown again; only its last four characters are.
What the app can access
The app asks for the least it needs, and only on the repositories you grant:
| Permission | Why |
|---|---|
| Contents: read | Commits, the files they changed, comparing releases, git blame, and push notifications |
| Metadata: read | Repository names and default branches (every GitHub App has it) |
| Issues: read and write | Opening GitHub issues from Guidely, linking existing ones, and seeing when they're closed |
It never writes code, opens pull requests or reads your organization's members. More detail, including how creating and installing it are secured, is in Integrations.