Docs · Connect your tools
Connect GitHub
StackWeaver reads settings on the repositories you choose and keeps what GitHub returns as evidence. This guide covers what it reads, what it does not do, the permissions it requests, the steps to connect, the settings to switch on in your own GitHub, and how to disconnect.
Last reviewed: 6 November 2026 · Describes what is live in production on that date. A result is evidence of what the provider returned at a time, nothing more.
1. What it collects
Once a day, and when a workspace owner or admin presses Run now, StackWeaver makes read-only checks per repository and keeps each result as an Evidence Object (how it works). It looks at each repository's default branch. Every result is stored with the exact GitHub response and a SHA-256 fingerprint, including results that fail (platform).
| Check (as shown in the portal) | What StackWeaver reads |
|---|---|
| Default-branch protection | Whether the default branch has branch protection. |
| Required pull-request reviews | How many approving reviews the protection requires before merging. |
| Required status checks | Whether any status checks must pass before merging. |
| Force-push and deletion blocked | Whether force pushes and deleting the branch are blocked. |
| Secret scanning and push protection | Whether secret scanning and push protection are on, as GitHub reports it in the repository settings. |
| Dependabot critical/high alerts | The count of open critical and high Dependabot alerts. |
Dependabot alert responses name the affected packages and the manifest files they were found in. Because StackWeaver stores the exact response, that information is kept as part of the evidence.
2. What it does not do
- It never writes and never changes a setting: the collector only sends GET requests (source).
- It never reads source code or file contents, and never reads issues or pull-request text.
- It does not issue certifications. A named reviewer, not software, decides whether evidence is accepted (editorial policy).
3. Permissions the StackWeaver GitHub App requests
All are read-only repository permissions. The app asks for repository permissions only: no account permissions and no write access (app settings).
| Permission | Why StackWeaver needs it | If it is missing |
|---|---|---|
| Metadata: read-only | To read the repository and its default branch (GitHub lists this under Metadata). | StackWeaver cannot read basic repository details, so its checks cannot run. |
| Administration: read-only | To read branch protection (GitHub requires it) and the secret scanning status, which GitHub returns only to a token with admin access (GitHub). | The four branch-protection checks show Could not check, with the message "The StackWeaver GitHub App cannot read branch protection (needs Administration: read)". Secret scanning shows Not enabled with "or the app cannot see it". |
| Dependabot alerts: read-only | To count open critical and high alerts (GitHub requires it). | The Dependabot check shows Could not check. |
"Administration" is a GitHub permission name. StackWeaver asks for the read-only level only and does not change any administration setting.
Permission names follow GitHub's own (permissions reference).
4. Connect steps
- Sign in to the StackWeaver portal as a workspace owner or admin.
- Open Evidence and find the GitHub evidence section.
- Press Connect GitHub. GitHub opens on its own page; nothing is typed into StackWeaver (how it works).
- Choose your personal account or your organisation. Organisation owners can install apps on their organisation (GitHub); if you are not an owner, ask one to approve the installation.
- Choose the repositories to share, then install. You choose which repositories the app can reach (GitHub).
- Back in StackWeaver, tick up to 20 repositories (limit), press Save repositories, then press Run now.
When StackWeaver adds a permission. GitHub notifies the owner of the account where the app is installed (GitHub). The owner can choose whether to accept the additional permissions. Until they do, the app keeps its current permissions (GitHub), and any check that needs the new permission shows Could not check.
5. Settings to switch on in your own repository
StackWeaver reports what GitHub returns. If a protection is not switched on, the honest result is Fail or Not enabled. These are the settings the checks look at. Whether each is available depends on your GitHub plan and your repository type; follow GitHub's own pages.
- Branch protection or rulesets on the default branch: required approving reviews, required status checks, and blocking force pushes and deletions. (About protected branches; About rulesets)
- Secret scanning and push protection. (About secret scanning; About push protection)
- Dependabot alerts. (About Dependabot alerts; Configuring Dependabot alerts)
6. Reading the results
| Label | What it means |
|---|---|
| Pass | GitHub returned a setting that meets the check when StackWeaver looked. |
| Fail | GitHub returned a setting that does not meet the check, for example a default branch with no protection. |
| Not enabled | The feature is switched off, or GitHub did not show it to the app. The message says which. |
| Could not check | StackWeaver was not permitted to read it, or GitHub did not answer. It does not mean the setting is fine, and it does not mean it is broken. |
| Check | Pass when |
|---|---|
| Default-branch protection | The default branch is protected. |
| Required pull-request reviews | At least one approving review is required before merging. |
| Required status checks | At least one status check must pass before merging. |
| Force-push and deletion blocked | Force pushes and branch deletion are both blocked. |
| Secret scanning and push protection | Secret scanning and push protection are both on. |
| Dependabot critical/high alerts | There are no open critical or high alerts. |
7. When it runs, and the Run now limit
StackWeaver collects once a day for every connected workspace. Run now can be used once every 10 minutes and 6 times a day per workspace (limit).
8. Disconnect and revoke
- In the StackWeaver portal, open Evidence, GitHub evidence, and press Disconnect. StackWeaver stops collecting. Evidence already collected stays.
- To remove the app's access in GitHub, open Settings, Applications, Installed GitHub Apps (GitHub), choose Configure next to StackWeaver, and click Uninstall (GitHub).
What remains. Past evidence stays in your workspace as the audit trail unless you ask for deletion. Under the privacy policy, engagement data is kept for the term of the engagement plus 3 years (retention) and deletion requests are actioned within 30 days, subject to legal-hold exceptions (retention). To ask for deletion, write to [email protected].
9. Troubleshooting
| What you see | What it means | What to do |
|---|---|---|
| The StackWeaver GitHub App cannot read branch protection (needs Administration: read) | The installation does not hold the Administration read permission, or an owner has not yet accepted it. | Ask an owner of the account to accept the updated permissions on the installation page, then press Run now. |
| Secret scanning is not available for this repository, or the app cannot see it | Secret scanning is off or not available for that repository, or the Administration permission is not in force. | Check the repository setting and the permission, then press Run now. |
| Dependabot alerts are switched off for this repository | Dependabot alerts are off. | Switch them on in the repository settings. |
| GitHub did not let StackWeaver read this installation, so nothing was connected | The app was uninstalled or suspended, or GitHub refused the request. | Check that the app is still installed, then press Connect GitHub again. |
| StackWeaver's own GitHub App key could not be used | This is on StackWeaver's side. Nothing was connected. | Write to us through the contact page; there is nothing to change on your side. |
| please wait: the collector can run once every 10 minutes, 6 times a day | The Run now limit was reached. | Wait and try again later; the daily collection still runs. |
Still stuck? Use the contact page.
Sources and method
Statements about GitHub and Okta link to their own documentation. Statements about StackWeaver link to the page that says them, or are recorded in a claims ledger with the file in StackWeaver's repository that they come from. See oureditorial policy. Spotted an error? Use the contact page.