# GitHub App Authentication for SCM Integration **Important** This feature is currently available for Sonatype Cloud and will be available for Sonatype Self-Hosted deployments in June. Sonatype Lifecycle can authenticate to GitHub through GitHub Apps for source control management (SCM) integration. GitHub App authentication provides secure, least-privileged, system-to-system access for SCM operations such as Golden PRs, Auto PRs, and pull request commenting. You can configure GitHub App authentication at the root organization, organization, or application level in Sonatype Lifecycle. At the root organization and organization levels, you can register and manage multiple GitHub Apps. At the application level, only one GitHub App can be configured. ## When to use GitHub App Authentication Use GitHub App authentication when you want Sonatype Lifecycle to interact with GitHub without relying on a personal access token (PAT) tied to an individual user account. Multiple GitHub Apps can be useful when: - A Lifecycle organization works with repositories from more than one GitHub organization or account. - Different teams manage their own GitHub App installations while sharing the same Lifecycle organization hierarchy. - You need to add a new GitHub App without replacing or deleting an existing GitHub App configuration. - You want to switch away from GitHub App authentication temporarily and switch back later without reinstalling apps. ## GitHub App Configuration Levels and Automatic Selection GitHub App authentication can be configured at these levels in Sonatype Lifecycle: | Lifecycle level | Multiple GitHub Apps supported? | Behavior | |---------------------------|----------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------| | Root organization | Yes | GitHub Apps configured at the root organization can be used by child organizations and applications when no nearer owner level has active GitHub Apps. | | Organization | Yes | GitHub Apps configured at an organization can be used by that organization and by child organizations or applications when that organization is the nearest owner level with active GitHub Apps. | | Application | No | An application can have only one GitHub App configured. After one GitHub App is configured at the application level, the **Add GitHub App** button is disabled for that application. | When Sonatype Lifecycle needs to perform an SCM operation, it looks for active GitHub Apps at the nearest applicable level in the Lifecycle hierarchy. If the nearest level has one active GitHub App, Lifecycle uses that app. If the nearest level has more than one active GitHub App, Lifecycle selects an app automatically for SCM operations based on the requesting Lifecycle owner. ****Repository access for multiple GitHub Apps**** Lifecycle does not select a GitHub App based on the repository URL. If more than one GitHub App is active at the same Lifecycle organization level, make sure each active GitHub App at that level has the repository access needed by the organizations and applications that can use that configuration. If different GitHub Apps should be used for different repository sets, configure those apps at the appropriate Lifecycle organization or application level so the intended child organizations or applications use the correct GitHub App configuration. ****Changes to the active app set**** When GitHub Apps are added, deleted, deactivated, or reactivated, the set of active apps available for selection can change. Because Lifecycle selects from the active apps at the nearest applicable level, some organizations or applications may use a different GitHub App after the active app set changes. ## GitHub App Authentication vs PAT Authentication | Feature | Personal access token (PAT) | GitHub App | GitHub App advantage | |--------------------------------------------|------------------------------------------------------------------------------------------------|----------------------------------------------------|------------------------------------------------------------------------------------------------------------------| | Security | Tied to a user's permissions, often with broad access. If leaked, the token carries that user's privileges. | Uses granular, fine-grained permissions. You can select the repositories and permissions the app can access during installation. | Reduces the risk of privilege escalation and limits the potential impact of compromised credentials. | Token lifespan | Long-lived and must be manually revoked. | Uses short-lived installation tokens that are refreshed automatically. | Limits the usable lifetime of an exposed token. | Identity and access | Tied to an individual user account. Access can be affected if the user leaves the organization or loses permissions. | Acts as an independent GitHub App installation and is not tied to a specific user account. | Improves continuity for automated SCM operations. | Repository access | Access is based on the repositories the token owner can access. | Repository access can be granted to all repositories or only selected repositories during installation. | Provides more control over which repositories the integration can access. | Automation | Actions are performed on behalf of the user who created the token. | Actions are performed by the GitHub App, making it suitable for automated tasks and CI/CD workflows. | Provides a clearer audit trail for automated SCM activity. ## Before you Begin Before configuring GitHub App authentication, make sure you have: - Permission in Sonatype Lifecycle to update the source control configuration for the root organization, organization, or application you are configuring. - GitHub permissions to create and install a GitHub App for the target GitHub organization or personal account. - Access to GitHub in another browser tab. You must be signed in to GitHub before starting the registration flow from Lifecycle. - The exact GitHub organization or account name. For organization accounts, use the name exactly as it appears in the repository URL. - A repository access plan for the GitHub App installation. During installation, you can grant access to all repositories or only selected repositories. - A plan for multiple GitHub Apps, if applicable. Apps configured at the same Lifecycle level should have repository access that supports the organizations and applications that can use that configuration. ****Root organization configuration**** Configuring GitHub App authentication at the root organization level requires GitHub owner permissions for the target GitHub organization. ## Configure GitHub App Authentication Use the Source Control page to configure GitHub App authentication for a root organization, organization, or application. 01. In Sonatype Lifecycle, select the root organization, organization, or application you want to configure, navigate to the _Source Control_ section, and open the configuration page. 02. In the _Source Control Management System_ dropdown, select _GitHub_. 03. Under Authentication, select _GitHub App_. 04. Select _Add GitHub App_. 05. In the registration dialog, enter the GitHub organization name or select a personal account. For organization accounts, specify the organization name exactly as it appears in the repository URL. 06. Select _Register & Create GitHub App_. 07. When redirected to GitHub, complete any required authentication or two-factor authentication prompts. 08. On the GitHub App creation page, enter a unique GitHub App name. If you do not enter a name, GitHub assigns a generated name automatically. 09. Select _Create GitHub App_. 10. On the GitHub installation screen, choose the repository access scope: - _All repositories_ grants the GitHub App access to all repositories in the selected GitHub organization or account. - _Only select repositories_ grants the GitHub App access only to the repositories you choose. 11. Select _Install & Authorize_ to complete the installation in GitHub. 12. After GitHub redirects you back to Sonatype Lifecycle, acknowledge the setup complete notification by selecting _Done_. 13. On the Source Control page, review the GitHub App details and select the pull request actions you want Lifecycle to perform for the configured repositories or applications. 14. Select _Create_ to save the GitHub App configuration, or select _Update_ if you are changing an existing configuration. ****Save the source control configuration**** If you do not select _Create_ (or _Update_) where prompted, the authentication settings are not saved in the Lifecycle source control configuration. ****Repository selection after installation**** You can update repository access after installation by changing the GitHub App installation settings in GitHub. If you use Easy SCM, reselect repositories there as needed after completing GitHub App authentication. ## Manage GitHub Apps Use the Manage GitHub Apps page to view registered GitHub Apps for a Lifecycle root organization, organization, or application, and to add or delete GitHub Apps. ### Open the Manage GitHub Apps page 1. In Sonatype Lifecycle, select the root organization, organization, or application you want to configure, navigate to the _Source Control_ section, and open the configuration page. 2. In the _Source Control Management System_ dropdown, select _GitHub_. 3. Under Authentication, select _GitHub App_. 4. Select _Manage GitHub Apps_. The Manage GitHub Apps page lists registered GitHub Apps in a table with columns for GitHub organization, GitHub application, date, and actions. Use this page to add or remove GitHub Apps. ### Add another GitHub App 1. On the Manage GitHub Apps page, select _Add GitHub App_. 2. Complete the same registration and installation flow used to configure a GitHub App. 3. After GitHub redirects you back to Lifecycle, confirm that the GitHub App appears in the Manage GitHub Apps table. ****Application-level limit**** Only one GitHub App can be configured for a Lifecycle application. If one GitHub App is already configured at the application level, the _Add GitHub App_ button is disabled for that application. This limit does not apply to Lifecycle organizations. ### Delete a GitHub App 1. Open the Manage GitHub Apps page and find the GitHub App you want to delete. 2. In the actions column, select the delete action, indicated by the trash can icon. 3. Confirm the deletion in the confirmation dialog. After deletion, the GitHub App is removed from Lifecycle and is no longer selected for SCM operations. If other active GitHub Apps remain at the same Lifecycle level, Lifecycle can select one of the remaining apps for future SCM operations. ****GitHub cleanup**** When you delete a GitHub App from Lifecycle, Lifecycle deletes the GitHub App record and attempts to remove the corresponding GitHub installation. The GitHub App registration can still exist in GitHub and must be deleted manually in GitHub if your organization requires full cleanup. ## Switch authentication methods For GitHub source control configuration, you can switch the authentication method between GitHub App authentication and Personal Access Token (PAT) authentication. | Change | What happens to GitHub Apps | |-------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | GitHub App to PAT | Lifecycle deactivates the GitHub Apps for that owner. The apps are not deleted, but they are not used while another authentication method is selected. | | PAT to GitHub App | Lifecycle reactivates installed GitHub Apps for that owner and makes them available for GitHub App authentication again. | This behavior lets you temporarily switch away from GitHub App authentication without reinstalling apps later. Deleted GitHub Apps are not restored when you switch back to GitHub App authentication.