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 :doc:`pull request
checks </guides/pr-integration/configure-github-app>`. 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.
