Adding GitHub Repositories

This guide includes authorizing your GitHub account with HackerOne, installing the the H1 Code GitHub application (PullRequest) to your Organization, and syncing with your repositories.

HackerOne's GitHub application for our code security product is an a verified application in GitHub's official marketplace listed as PullRequest.

This application is compatible for GitHub Organizations using:

• GitHub.com (Cloud)

• GitHub Enterprise Cloud

Need instructions for GitHub Enterprise Server (on-premise)? See our On-Premise Integration Guide.

Dataflow Diagram

For a visualization of how H1 Code and our systems interact with your GitHub Organization and authorized repositories, see and download the diagram below.

Dataflow diagram

HackerOne Dataflow Diagram GitHub.png

image · 208KB

Open

Click to download

Step 1: Authorize and Connect

After signing up, you'll be prompted to authorize and connect with a version control hosting provider. Click the Sync with GitHub option.

GitHub Enterprise: Users with Enterprise Owner permissions are required to sign up by configuring a user name and password (not via the Sign in with GitHub option) before connecting projects and authenticating with GitHub.

You'll then be asked to authorize your GitHub user account with PullRequest.

Step 2: Install the PullRequest GitHub app

After authorizing with your GitHub account, you'll be directed to a page to select which GitHub Organization you want to install PullRequest on.

NOTE: Every GitHub user account is treated like an Organization and will be shown in this list. It's likely you'll need to connect to your company's Organization instead of your GitHub user's Organization (see below).

You can click here to access this page directly.

Be sure to select the GitHub Organization your team uses rather than your GitHub username.

If a GitHub Profile or Organization already has PullRequest installed, the text Configure will appear on the selection.

GitHub Organizations with a "Configure" option already have the PullRequest app installed.

Q: I don't see the Organization I'm trying to add. How do I add it?

A: You'll need to reach out to an Owner of your GitHub Organization with this link to complete the integration. We recommend also including the explanation of permissions which describes what we need the integration permissions for and how we use them.

To determine who in your GitHub Organization has an Owner role, follow these steps.

Step 3: Select Repositories

You'll be asked to allow PullRequest to access All Repositories or Only select repositories.

After you've made your selection, click the Install button.

Required Permissions

Our integration adheres to the principle of least privilege, ensuring that it only has the access necessary to perform its intended function—providing valuable insights in pull request discussions. Here are the permissions we require and how we use them.

Required Permissions for GitHub.com and GitHub Enterprise Cloud Integration Commit Statuses (Read and Write) This allows our service to to mark the status of our scanning and validation operations based on relevant commits. These states include: error, failure, pending, or success. Statuses will be visible from the pull request in GitHub to let end users know a scan is in progress. When it completes, they'll see a high-level description of the outcome of the scan.

Issues (Read and Write) We use the Issues permission to subscribe to events related to a pull request comment and for updating comment state (e.g., mark an inline comment as "Resolved"). GitHub's REST API considers every pull request an issue, which is why we need it in addition to the Pull Requests permission.

Pull requests (Read and Write) This permission allows our system to detect pull requests, information about them our system needs for determining workflow executions and so end-users can interact with the service from the GitHub interface.

Our service never updates or deletes source code in your repository. Our integration DOES NOT execute any code-modifying operations. Members (Read-only) Our system uses this permission to get and list members of the GitHub Organization which can be assigned service licenses in our systems and so it can determine what teams are visible to end-users. Contents (Read-only) This allows our service to get contents of a repository as needed for code scanning and validation. For example, certain files within a repository that are unchanged in the pull request code diff may still be relevant for determining reachability of a detected issue. The Contents permission allows our system to call to GitHub with a path parameter to reference the contents it needs. Metadata (Read-only) The Metadata permission is required for all GitHub applications. This allows our system to list repositories, contributors, know what contributors have access to, and ensure any changes in GitHub are up-to-date in our systems. Email addresses (Read-only) When a member of your team creates a user account, our system uses this permission to apply the email address for their GitHub user to user profile in our systems. We use email communication for service events, occasional product release notes, and in case our staff need to reach out directly.

IP Allowlisting

If your GitHub Enterprise organization uses an IP allow list and the Projects page shows "No projects found" after completing the steps above, your IP allow list may be blocking our application's API access.

The HackerOne Code GitHub App declares its own IP addresses. To allow access, enable "IP allow list configuration for installed GitHub Apps" in your organization or enterprise security settings. GitHub documents this under Allowing access by GitHub Apps and Managing allowed IP addresses for your organization.

If your organization manages IP restrictions at the Enterprise level rather than the organization level, an Enterprise Admin will need to enable this setting.

Step 5: View Repositories

Your repositories should now appear on our dashboard page when the GitHub Organization is selected from the Organizations drop-down menu at the top-left portion of the screen.

NOTE: This guide contains screenshots from third-party partner interfaces that may be modified without notice. If you have any issues or questions about connecting with PullRequest, please reach out to [e-mail].