Note: Hyperproof connects to many third-party systems that frequently change, including the system interface. Contact your System Administrator or the third-party provider for assistance in meeting the requirements for integrating with Hyperproof and collecting the proof you need.
Hyperproof supports OAuth, 2FA (Two-Factor Authentication), and personal access tokens for GitHub authentication.
Note: Service accounts are recommended for integrations between Hyperproof and other applications. Service accounts are easier for your IT admin to maintain and ensure that your integrations will continue running when individuals change roles or leave the company.
This Hypersync supports importing a user list for an access review. See Importing a list of application users with a Hypersync for more information.
When you create a Hypersync between Hyperproof and GitHub, you can automatically collect the following proof types:
GitHub proof types and fields
Proof type | Fields | Testable |
Branch Protection | Branch Pattern, Applied branches, Branch Protection Enabled, Require a pull request before merging, Required number of approvals, Dismiss stale pull request approvals when new commits are pushed, Require review from Code Owners, Include administrators, Require status checks to pass before merging | Yes |
Commit Details | Commit SHA, Author, Message, Date Stats: Total, Additions, Deletions Files: File Name, File Status | No |
Commits | Commit SHA, Author, Message, Date | Yes |
External Repository Members | Username, Name, Email, Permissions | Yes |
Issue Details | Note: Fields on this proof may vary based on your GitHub settings | No |
List of Issues | Title, Body, State, Author, Created, Closed, Assignee, Locked, Labels | Yes |
Member Repository Access | Repository, Permissions | Yes |
Organization Members | Username, Name, Email, Role | Yes |
Pull Requests | Pull Request, Title, URL, Merged At, Merged By Reviewed By: Reviewer, State, Message, Submitted At | No |
Repository Admins | Repository, Access, Username, Name, Email | Yes |
Repository Members | Direct Access: Username, Name, Email, Permission Organization Access: Username, Name, Email, Permission | No |
Repository Rulesets | Ruleset name, Enforcement status, Target, Bypass actors, Require pull request, Required approvals, Dismiss stale pull request approvals when new commits are pushed, Require linear history, Block force pushes, Require status checks to pass before merging, Restrict deletions | Yes |
Repository Workflows | Repository, Workflow name, State | Yes |
Team Members | Organization, Team, Username, Name, Email, Role | Yes |
Automated control tests
Hyperproof has a collection of preconfigured, ready-to-deploy, customizable automated tests spanning a wide array of integrated services and proof types. For information on available tests for proof collected by this Hypersync, see the Automated control test library and Using the automated control test library.
GitHub permissions
GitHub permission requirements vary depending on the authentication type you use.
GitHub permissions by proof type when authenticating with OAuth or2FA
Proof type | Required permissions |
Branch Protection | Admin access to the repository to either write or maintain roles. |
External Repository Members | Push access to the repository. |
Member Repository Access | Admin access to the repository. |
Repository Admins | Admin access to the repository. |
Repository Members | Push access to the repository. |
Repository Rulesets | Requires the |
Repository Workflows | Admin access to the repository to either write or maintain roles. |
GitHub permissions required when authenticating with Personal Access Tokens
Hyperproof supports both fine-grained and classic personal access tokens for authentication purposes.
Read-Only repository access
Collects all proof types except Repository Rulesets.
Fine-Grained Token:
Repository Permissions:
Metadata,Contents,Issues,Pull requests,Actions,Administration(Set all to Read)Organization Permissions:
Members(Read)Requirement: Token resource owner must be set to the target GitHub Organization.
Classic Token:
Scopes:
repo,read:user,user:email
Admin repository access
Collects all proof types.
Fine-Grained Token:
Repository Permissions:
Metadata,Contents,Issues,Pull requests,Actions,Administration(Set all to Read)Organization Permissions:
Members(Read),Administration(Read & Write)Requirement: Token resource owner must be set to the target GitHub Organization.
Classic Token:
Scopes:
repo,read:user,user:email,admin:org
Additional documentation
Note: You only need to connect Hyperproof to the app once, and then you can create as many Hypersyncs as you need.
Additionally, you can create multiple Hypersyncs for a single control or label.
Tip: If you accidentally click Authorize Hyperproof during the connection process and your organization doesn’t have a green check next to it, go to your GitHub settings and revoke permissions for Hyperproof. Once the permissions are revoked, follow the steps to reconnect Hyperproof to GitHub.
Requesting organizational approval for using third-party apps in GitHub
If your organization is using a service account to connect GitHub to Hyperproof, and the account has restricted third-party apps, you’ll need to request approval for Hyperproof.
Once the request is approved by the organization’s owner, the GitHub organization should appear in the Owner drop-down menu within the Set up Hypersync window.
This process generates an auth token that is tied to the GitHub organizations you select. Users can only see the organizations selected during this process, and the list of organizations can't be changed once the auth token is created. To modify the list of organizations, you must revoke Hyperproof's app access and reconfigure the approval for using Hyperproof. See GitHub troubleshooting.
Log in to GitHub with the service account.
In the upper-right corner of any page, click your profile photo, then click Settings.
From the left menu, below Integrations, click Applications.
Select the Authorized OAuth Apps tab.
In the list of applications, click Hyperproof.
Below Organization access, click Request for each organization that needs authorization.
Note: Once the approval is in place, the list of organizations can't be updated. Revoke access and reconfigure the approval for Hyperproof.
Click Request approval from owners.
Full instructions can be found in the GitHub documentation.
A note about using 2FA with the Hypersync for GitHub
If you experience an issue establishing a service account connection for the Hypersync for GitHub, it may be because you have 2FA (Two-Factor Authentication) configured on your GitHub instance.
It is possible to create a service account in GitHub with 2FA. Refer to this GitHub article for more information. For reference, Hyperproof uses Bitwarden’s TOTP key generator for similar 2FA scenarios.