> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub OAuth 2.0 (GitHub App) connector profile – StackOne setup guide

> Set up a connector profile using OAuth 2.0 (GitHub App) for GitHub in StackOne to allow users to link their accounts.

> [!WARNING]
>
> Owner privileges in your GitHub organization or admin access to your GitHub account are required to create a GitHub App.

Select Actions to adjust the guideSome actions may require additional configuration in the provider to be accessible. Choose the actions you need and the guide will be updated.

Select all
Clear

ActionScope(s)

Loading actions...No actions match your search.

Dynamic Guide URL

Copy URL

Scopes Selected

<pre role="textbox" aria-readonly="true" tabIndex="0" />

Separator

Copy scopes

## Register a GitHub App

Create the GitHub App under your personal account or under the organization StackOne should read.

**1. Start a new GitHub App**

Sign in to your [GitHub account](https://github.com/login), then open the **GitHub Apps** page for the account that will own the app.

<ul>
  <li>**Personal account:** Open **Settings** > **Developer settings** > **GitHub Apps**.</li>
  <li>**Organization:** Open the organization, then open **Settings** > **Developer settings** > **GitHub Apps**.</li>
  <li>Click **New GitHub App**.</li>
</ul>

**2. Fill in the basic information**

Name the app at the top of the form.

<ul>
  <li>**GitHub App name**: `StackOne Integration`, or a name you prefer</li>
  <li>**Homepage URL**: your company's website</li>
</ul>

**3. Set up user authorization**

Fill in the **Identifying and authorizing users** section.

<ul>
  <li>**Callback URL**: copy it from your Connector Profile</li>
  <li>Select **Expire user authorization tokens**.</li>
  <li>Clear **Request user authorization (OAuth) during installation**.</li>
</ul>

**4. Turn off the webhook**

Under **Webhook**, clear **Active**.

**5. Add permissions for access reviews and compliance checks**

Enables actions: Check Organization Membership, Create Pull Request, Create Pull Request Review, Create Pull Request Review Comment, Get Branch, Get Branch Protection, Get Branch Rules, Get Combined Status For Ref, Get Commit, Get Git Reference, Get Latest Release, Get Organization, Get Organization Membership, Get Organization Ruleset, Get Pull Request, Get Repository, Get Repository Content, Get Repository Ruleset, Get Team, Get Unified Group, Get Unified Organization, Get Unified Role, Get User, List Authenticated User Organizations, List Authenticated User Repositories, List Branches, List Check Runs For Ref, List Collaborators, List Commits, List Forks, List Matching Git References, List Organization Audit Log, List Organization Branch Protection, List Organization Members, List Organization Members With Two-Factor Status, List Organization Repositories, List Organization Rulesets, List Outside Collaborators, List Pull Request Reviews, List Pull Requests, List Pull Requests For Commit, List Releases, List Repository Rulesets, List Repository Teams, List Team Members, List Team Repositories, List Teams, List Unified Groups, List Unified Organizations, List Unified Roles, List Unified Users, List User Organizations, List User Repositories, List Users, Merge Pull Request, Search Code, Search Issues, Search Pull Requests With Reviews, Search Repositories, Update Organization, Update Pull Request

For user access reviews, two-factor status, branch protection, reviews and checks, set each of these to **Read-only**, and choose the access for organization **Administration**.

<ul>
  <li>**Organization permissions** > **Members**</li>
  <li>**Organization permissions** > **Administration**: **Read-only**, or **Read and write** to also read organization rulesets</li>
  <li>**Repository permissions** > **Administration**</li>
  <li>**Repository permissions** > **Metadata**</li>
  <li>**Repository permissions** > **Contents**</li>
  <li>**Repository permissions** > **Pull requests**</li>
  <li>**Repository permissions** > **Checks**</li>
  <li>**Repository permissions** > **Commit statuses**</li>
</ul>

<ul>
  <li>
    MembersRead
  </li>

  <li>
    OrganizationAdministrationRead
  </li>

  <li>
    OrganizationAdministrationWrite
  </li>

  <li>
    AdministrationRead
  </li>

  <li>
    MetadataRead
  </li>

  <li>
    ContentsRead
  </li>

  <li>
    PullRequestsRead
  </li>

  <li>
    ChecksRead
  </li>

  <li>
    CommitStatusesRead
  </li>
</ul>

**6. Add permissions for other actions**

Enables actions: Add Collaborator, Add Team Member, Add Team Repository, Cancel Workflow Run, Check Organization Membership, Create Deployment, Create Deployment Status, Create Git Reference, Create Issue, Create Issue Comment, Create Or Update File, Create Organization Repository, Create Pull Request, Create Pull Request Review, Create Pull Request Review Comment, Create Release, Create Team, Create User Repository, Create Webhook, Delete Deployment, Delete File, Delete Git Reference, Delete Release, Delete Repository, Delete Team, Delete Webhook, Download Artifact, Fork Repository, Get Authenticated User, Get Branch, Get Branch Protection, Get Branch Rules, Get Combined Status For Ref, Get Commit, Get Git Reference, Get Issue, Get Latest Release, Get Organization, Get Organization Membership, Get Organization Ruleset, Get Pull Request, Get Repository, Get Repository Content, Get Repository Ruleset, Get Team, Get Unified Credentials, Get Unified Group, Get Unified Organization, Get Unified Role, Get User, Get Webhook, Get Workflow Run, Invite Organization Member, List Artifacts, List Authenticated User Organizations, List Authenticated User Repositories, List Branches, List Check Runs For Ref, List Code Scanning Alerts, List Collaborators, List Commits, List Dependabot Alerts, List Deployments, List Forks, List Issue Comments, List Issues, List Matching Git References, List Organization Audit Log, List Organization Branch Protection, List Organization Members, List Organization Members With Two-Factor Status, List Organization Repositories, List Organization Rulesets, List Outside Collaborators, List Pull Request Reviews, List Pull Requests, List Pull Requests For Commit, List Releases, List Repository Rulesets, List Repository Teams, List Secret Scanning Alerts, List Team Members, List Team Repositories, List Teams, List Unified Groups, List Unified Organizations, List Unified Roles, List Unified Users, List User Organizations, List User Repositories, List Users, List Webhooks, List Workflow Jobs, List Workflow Runs, Merge Pull Request, Ping Webhook, Re-run Workflow, Remove Collaborator, Remove Organization Member, Remove Team Member, Search Code, Search Issues, Search Pull Requests With Reviews, Search Repositories, Star Repository, Trigger Workflow, Unstar Repository, Update Code Scanning Alert, Update Dependabot Alert, Update Git Reference, Update Issue, Update Organization, Update Pull Request, Update Release, Update Repository, Update Secret Scanning Alert, Update Team, Update User, Update Webhook, Upload Release Asset

Add these only for the actions you plan to use.

<ul>
  <li>
    ActionsRead
  </li>

  <li>
    ActionsWrite
  </li>

  <li>
    AdministrationRead
  </li>

  <li>
    AdministrationWrite
  </li>

  <li>
    ContentsRead
  </li>

  <li>
    ContentsWrite
  </li>

  <li>
    DeploymentsRead
  </li>

  <li>
    DeploymentsWrite
  </li>

  <li>
    EmailAddressesRead
  </li>

  <li>
    IssuesRead
  </li>

  <li>
    IssuesWrite
  </li>

  <li>
    MembersRead
  </li>

  <li>
    MembersWrite
  </li>

  <li>
    MetadataRead
  </li>

  <li>
    OrganizationAdministrationRead
  </li>

  <li>
    OrganizationAdministrationWrite
  </li>

  <li>
    ProfileRead
  </li>

  <li>
    ProfileWrite
  </li>

  <li>
    PullRequestsRead
  </li>

  <li>
    PullRequestsWrite
  </li>

  <li>
    SecurityEventsRead
  </li>

  <li>
    WebhooksRead
  </li>

  <li>
    WebhooksWrite
  </li>

  <li>
    ChecksRead
  </li>

  <li>
    CommitStatusesRead
  </li>

  <li>
    CodeScanningAlertsWrite
  </li>

  <li>
    DependabotAlertsWrite
  </li>

  <li>
    SecretScanningAlertsWrite
  </li>

  <li>
    StarringWrite
  </li>

  <li>
    WorkflowsWrite
  </li>
</ul>

**7. Create the app**

At the bottom of the form, find **Where can this GitHub App be installed?**.

<ul>
  <li>Select **Only on this account** or **Any account**. **Only on this account** lets you install the app only on the account it is registered under, so register it under the organization to install it there.</li>
  <li>Click **Create GitHub App**.</li>
</ul>

**8. Copy the credentials**

Both credentials are on the app's page, which opens after you create the app.

<ul>
  <li>Copy the **Client ID** into your Connector Profile.</li>
  <li>Under **Client secrets**, click **Generate a new client secret**.</li>
  <li>Copy the **Client Secret** into your Connector Profile. GitHub shows it only once.</li>
</ul>

**9. Turn on refresh tokens**

In the app's sidebar, open **Optional features**.

<ul>
  <li>Next to **User-to-server token expiration**, click **Opt-in**. If the button reads **Opt-out**, it is already on.</li>
</ul>

**10. Install the app**

Install the app on your account or organization to give access to private repositories, organization data and app-level permissions. You can install it before or after an account is linked.

<ul>
  <li>In the app's sidebar, click **Install App**.</li>
  <li>Click **Install** next to the account or organization StackOne should read.</li>
  <li>Select **All repositories**, or select specific repositories. For compliance checks, select **All repositories** so every repository is included.</li>
  <li>Click **Install**.</li>
</ul>

## Create the StackOne Connector Profile

**1. Create a Connector Profile**

Enable the connector and create a Connector Profile in your project. See [Setup Connector Profile](https://docs.stackone.com/gateway/quickstart.md#setup-connector-profile).

**2. Link an Account**

Once the Connector Profile is created, continue to [link an account](https://docs.stackone.com/connectors/github/guides/link-account/oauth-2-0-github-app.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.