Use a GitHub App for Repository Access

CodeScene can clone and update private GitHub repositories using a GitHub App. This is an alternative to using SSH keys or embedding a username and token in each HTTPS repository URL.

Use this option when your organization requires GitHub App authentication or when you want repository access to be limited to the repositories where the app is installed.

You can use the same GitHub App for repository access and pull request checks. A repository-access-only GitHub App does not require a webhook configuration and only needs read access to repository contents. An app used for pull request checks requires the additional permissions and webhook configuration described in the pull request checks guide.

Create and Install the GitHub App

  1. In GitHub, create a GitHub App for the GitHub host that serves your repositories. For GitHub.com, the host is github.com.

  2. Give the app read-only access to repository contents. GitHub automatically grants the metadata permission required by every GitHub App.

  3. Generate and download a private key for the app. GitHub downloads this as a .pem file.

  4. Install the app on the organization or user account that owns the repositories. Select all repositories or only the repositories that CodeScene will analyze.

  5. Copy the GitHub App ID from the app’s settings page.

Create a GitHub App Preset in CodeScene

You must be a CodeScene administrator to create the preset.

  1. Open Configuration -> Settings Presets. To limit access to a project group, open that group’s Settings Presets tab instead.

  2. Create a GitHub App preset.

  3. Enter a descriptive label, the GitHub host, the GitHub App ID, and upload the downloaded .pem private key.

  4. Save the preset.

Project-group presets are available to projects in that group and its subgroups. Use a global preset when the same GitHub App should be available to all projects. You can also select an existing PR Check - GitHub App preset for repository access when it is configured for the same GitHub host.

Use the Preset for a Project

When you create a project, enter a credential-free HTTPS repository URL, for example https://github.com/acme/service.git. CodeScene shows a GitHub App selection for each matching GitHub host. Select the preset created above and continue creating the project.

You can also select the preset from the repository configuration of an existing project. CodeScene uses the selected app to obtain short-lived GitHub installation tokens when cloning and updating repositories.

Only credential-free HTTPS URLs use the selected GitHub App. SSH URLs and HTTPS URLs containing a username or token keep their existing authentication method. The configured host must exactly match the repository URL host, and the GitHub App must be installed with access to every repository CodeScene needs to clone.