Connect GitHub

1. 1

   Open Integrations

   In your workspace dashboard, open the Integrations tab. It lists your workspace connections: the identities Sarcio uses to open fix PRs, post the sarcio/approval check, read CI and dispatch remote builds. They belong to the workspace, not to a person. Tokens are encrypted at rest and never shown again after you save them. QA members don't see this tab.

   

   Enlarge

2. 2

   Install the Sarcio GitHub App (recommended)

   On the Integrations tab, under Add a connection, press Install the GitHub App. On GitHub the app is named Sarcio AI, and its public page is github.com/apps/sarcio-ai. Start from the Integrations tab rather than that page, so Sarcio can record the installation. GitHub asks where to install it: pick the organization (or your own account) that owns the repository, then Only select repositories and choose the repositories your Sarcio sites point at, and press Install & Authorize. That one step also authorizes the app. Sarcio uses that only to confirm your GitHub account can see the installation you just made, revokes it straight away, and lands you back on Integrations with the installation listed.

   • Pull requests and commits come from sarcio-ai[bot], so a teammate can review and approve them, and nothing breaks when someone leaves.
   • Sarcio stores the installation id and the account it covers, never a token: it mints a one-hour token each time it needs one.
   • The sarcio/approval result is a check run with the approvers and a link to the report.
   • Repositories in another organization need their own install: press Install on another account. Sarcio picks the installation on each repository's owner.
   • If you are not an owner of the organization, GitHub sends the owner a request instead. Once they approve it, press Install again to record it in Sarcio.

   

   Enlarge

   Already installed for another workspace?

   GitHub installs an app once per account. If the organization already has the app (for another Sarcio workspace, say), pressing Install opens that installation's settings on GitHub and never comes back, so nothing is recorded. Press Already installed? Connect it instead. GitHub asks you to authorize the app, and Sarcio attaches the installations your GitHub account can access on the accounts that own this workspace's GitHub site repositories. Make sure the installation's selected repositories include this workspace's repositories.

   What the app can access

   The owner who installs the app accepts these repository permissions, and only on the repositories they chose:

   • Contents (read and write): clone the repository and push the fix branch.
   • Pull requests (read and write): open the fix pull request and see when it merges.
   • Checks (read and write): post sarcio/approval and read your GitHub Actions result.
   • Commit statuses (read and write): read CI that reports through statuses.
   • Actions (read and write): dispatch the build workflow; used only when a site has remote builds on.
   • Metadata (read): required by GitHub for every app.

   It asks for no administration, secrets, workflow-file, webhook, member, organization or account permissions, so it can't change settings, read secrets or edit your CI configuration.

   Each installation shows its account, whether it covers all or selected repositories, and a Manage on GitHub link for adding repositories or uninstalling. Remove only forgets the installation in Sarcio; uninstall it on GitHub to revoke its access. If GitHub suspends or uninstalls it, Sarcio marks it and stops using it at once. The permissions it asks for are listed under Repository access.

   Already connected with a personal account?

   It keeps working, and the app takes over for every repository it covers. Once the app covers all of your sites' GitHub repositories, the Personal banner offers Remove the old personal connection, which also revokes its OAuth token. Pull requests already open keep syncing; new ones come from the bot.
3. 3

   Or: create a fine-grained token on a bot account

   Use this on GitHub Enterprise Server, or where your organization does not allow apps. Sarcio's pull requests and commits appear as whoever owns the token. Give it an account of its own, so they read as Sarcio's work, a teammate can review and approve them, and nothing breaks when someone leaves.

   • Create a GitHub account for Sarcio, for example acme-sarcio. Add it to the organization (or as a collaborator) with write access to the repositories your Sarcio sites point at, and nothing else. On a paid organization plan it uses a seat.
   • Signed in as that account, go to Settings → Developer settings → Personal access tokens → Fine-grained tokens → Generate new token.
   • Resource owner: the organization that owns the repository (or the account itself for a personal repo).
   • Expiration: set one, and put a reminder in your calendar to rotate it.
   • Repository access: Only select repositories, then choose the repositories your Sarcio sites point at.
   • Repository permissions: Contents Read and write, Pull requests Read and write, Commit statuses Read and write (the sarcio/approval check) and Checks Read-only (to show your GitHub Actions result in Sarcio). Add Actions Read and write only if a site uses remote builds. GitHub adds Metadata (read) on its own. Nothing else is needed.

   Don't use a classic token

   Classic tokens can't be limited to one repository: even the narrowest one that can open a pull request carries full repo access to every private repository the account can see, and they often pick up admin:org or delete_repo along the way. Sarcio needs none of that.
4. 4

   Save the token in Sarcio

   On the Integrations tab, under Code hosts, find Add a bot or project access token (recommended). Enter github.com as the host, leave the provider on Auto-detect, paste the token and press Save token.

   When you save, Sarcio asks GitHub who the token belongs to (GET /user, an identity read that needs no extra permission) and badges the connection. GitHub reports only app identities as bots. A machine user is an ordinary GitHub user account, so its token shows Personal with a banner. That is expected for a dedicated machine user; the GitHub App shows App. If GitHub can't be reached, the token still saves, badged Owner unknown.

   What Sarcio checks, and what the warnings mean

   Sarcio also reads each repository your sites point at on github.com (GET /repos/{owner}/{repo}) and the token's expiry from the github-authentication-token-expiration header GitHub sends. Warnings show on the connection and never stop the save:

   • Can't reach owner/repo. The fine-grained token's repository access doesn't include it, or the site's owner or name is wrong.
   • Can't push to owner/repo. Grant Contents: Read and write.
   • Missing repo scope. A classic token without repo.

   The expiry shows as a chip on the connection, and workspace admins get an email 14 and 3 days before it, once per threshold. Press Re-check on the connection after changing the token's access on GitHub.

   

   Enlarge

5. 5

   Quick start: connect a personal account

   Trying Sarcio out? Under Quick start: connect a personal account, press Connect GitHub and approve the app on GitHub. There is no token to copy, and access refreshes on its own. GitHub skips the consent screen when the account has already authorized the app, so you may land straight back on Integrations.

   It is quick, but it connects the workspace as you:

   • Fix PRs and commits appear as you, and GitHub won't let you approve a pull request you authored.
   • GitHub's OAuth repo scope reaches every repository your account can, not just the ones Sarcio patches.
   • The connection stops working if you leave or lose access.
   • The connection wears the Personal badge, with a warning banner on the Integrations tab.

   Connecting over OAuth replaces a token saved for the same host, and saving a token replaces an OAuth connection. Neither touches a GitHub App installation, which Sarcio prefers wherever it covers the repository. Move to the app before your team relies on it.

6. 6

   Organization repositories: grant access

   The GitHub App needs no separate grant: the owner's install approval is the grant, scoped to the repositories they picked. An organization can require an owner to approve fine-grained tokens that target it. If yours does, an owner approves the bot account's token request once, under the organization's settings.

   The personal quick start meets a different gate. Organizations can turn on OAuth App access restrictions. With them on, an OAuth connection authenticates fine but every pull request fails with GitHub 403: the organization has enabled OAuth App access restrictions. An organization owner has to approve the app once:

   • The owner opens GitHub → Settings → Applications → Authorized OAuth Apps and selects the Sarcio app.
   • Under Organization access, they press Grant next to the organization. (A member who isn't an owner sees Request instead, and an owner approves the request.)

   The organization's Settings → Third-party application access policy then lists the app as Approved. Leave the restriction itself on so every other app still needs approval. Don't press Remove restrictions.

   

   Enlarge

7. 7

   Point the site at its repository

   On the Sites tab, press Manage next to the site and open Repository & source. Fill in the repository and the file a fix edits. What each field means.

   Repository & source

   Forge host          github.comRepo owner          acmeRepo name           storefrontDefault branch      mainSource file         src/pages/home.tsxServer source file  server/routes/newsletter.ts

8. 8

   Approve a patch and get a pull request

   When a reviewer approves a patch and it goes live, Sarcio opens a pull request against the default branch. A front-end or server-side fix carries a one-file source change; a code fix commits the source files it was built from. Every PR has a Sarcio context section with the original report, the live patch operations, the AI's explanation and the patch expiry, plus who approved it and a link to the report in Sarcio. With Jira connected, the title and branch carry the ticket key, so the PR links itself to the ticket.

   Text

   Branch   sarcio/<ticket>-fix-<patch id>   (sarcio/fix-<patch id> without a ticket)Title    your commit template, e.g. "{ticket} {summary}"Change   the site's Source file, or its Server source file for a server fixTrailer  Approved-in-Sarcio-by: Ada L.   (one per approver)

   Approvers are named, never by email. Each commit gets one Approved-in-Sarcio-by trailer per approver. Sarcio never adds Co-authored-by, because approving a fix isn't writing it.

   Get @mentioned: link your GitHub account

   Any member can open Account and press Link GitHub. GitHub asks for no scopes, and Sarcio stores no token. Pull requests you approved then name you as @your-login, so GitHub notifies you. If an admin turns on acting links, you can also let Sarcio act as you. What a link can and cannot do.

   

   Enlarge

   

   Enlarge

   

   Enlarge

   Require Sarcio's approval before merging

   The pull request's head commit carries a sarcio/approval check (a check run when the GitHub App opened the PR, a commit status on the token path), set to success with the approvers' names and the risk rating (for example Approved in Sarcio by Ada L. and Bo K. · elevated risk) and linking to the report. If the live patch is retired or expires before the pull request merges, the check turns failed. To make it a merge gate, add a branch protection rule (or ruleset) on the default branch with Require status checks to pass and pick sarcio/approval. It appears in the picker once Sarcio has posted it on one pull request.

   Sarcio also reads your CI result on the pull request (GitHub Actions check runs and commit statuses) while it is open, and shows it as a Build: passing / failing / running chip next to the pull request on the report page and in Live patches.

9. 9

   If the pull request fails, retry it

   The fix stays live. Fix the cause (usually step 6, a suspended app or an expired token), then press Retry pull request on the report page. See retrying a pull request.

   

   Enlarge

Troubleshooting

• The installation shows Suspended. An owner suspended or uninstalled the app on GitHub. Unsuspend or reinstall it, then Retry pull request.
• "Your GitHub account cannot access that installation". The GitHub account that authorized the app during install can't see the installation, usually because you were signed in to a different account. Sign in to an account that can manage the installation and install again.
• "Waiting for an organization owner". You requested the install as a member. Once an owner approves it on GitHub, press Install the GitHub App again.
• A repository isn't covered. The installation was made with selected repositories that leave it out. Use Manage on GitHub to add it; Sarcio picks the change up as soon as GitHub reports it.
• 403 "OAuth App access restrictions". The organization hasn't approved the personal quick start's OAuth app. Follow step 6, then Retry pull request, or install the GitHub App instead.
• 401 Bad credentials. The token expired or was revoked, or someone revoked the OAuth app on GitHub. Save a new token or press Connect GitHub again, then retry.
• Repository not found, or refused before cloning. Sarcio checks access before it clones. A fine-grained token that doesn't include the repository, or a site with the wrong owner or name, fails that check. Add the repository to the token or fix the site settings.
• The connection shows Personal or Owner unknown. Personal means the token belongs to a user account. For a dedicated machine user that is expected. Owner unknown means Sarcio couldn't ask GitHub when you saved; press Re-check on the connection.
• Connect GitHub signed in the wrong account. GitHub reuses the account you're signed in to and skips consent if it authorized the app before. Revoke the app under Settings → Applications → Authorized OAuth Apps, sign in to the right account, and connect again.
• After connecting you land on another dashboard address. Older deployments return from the provider to a shared dashboard address instead of your workspace. The connection is saved either way: go back to your workspace address (e.g. acme.sarcio.io) and it's listed on the Integrations tab.

For the exact permissions the GitHub App and a GitHub token need, the OAuth scope the quick start requests, and what Sarcio deliberately never asks for, see Repository access. Next: connect Jira or run your first fix.