GitHub App Authentication for SCM Integration
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.
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.
In the Source Control Management System dropdown, select GitHub.
Under Authentication, select GitHub App.
Select Add GitHub App.
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.
Select Register & Create GitHub App.
When redirected to GitHub, complete any required authentication or two-factor authentication prompts.
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.
Select Create GitHub App.
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.
Select Install & Authorize to complete the installation in GitHub.
After GitHub redirects you back to Sonatype Lifecycle, acknowledge the setup complete notification by selecting Done.
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.
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
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.
In the Source Control Management System dropdown, select GitHub.
Under Authentication, select GitHub App.
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
On the Manage GitHub Apps page, select Add GitHub App.
Complete the same registration and installation flow used to configure a GitHub App.
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
Open the Manage GitHub Apps page and find the GitHub App you want to delete.
In the actions column, select the delete action, indicated by the trash can icon.
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.