Skip to main content

Connect and Onboard Repositories

Connect Agent P to GitHub to automate dependency upgrades across your repositories. This page walks through all the steps of the Agent P onboarding flow.

Complete the Prerequisites before you begin.

Connect Your GitHub Organization

Connecting your GitHub organization installs the Sonatype Guide GitHub App and grants Agent P access to the repositories you select.

You complete this procedure only once for each GitHub organization. After the connection is established, you can grant Agent P access to additional repositories without reinstalling the GitHub App.

Install the GitHub App.

  1. Sign in to guide.sonatype.com and open Agent P.

  2. Select Connect with GitHub.

  3. Authenticate with GitHub, then choose the GitHub organization and repositories that Agent P should access.

  4. Confirm the installation.

You can grant Agent P access to additional repositories later from Manage Connections on the Agent P dashboard.

Onboard and Configure Repositories

Onboard repositories to connect them to Agent P, apply configuration, and enable automated dependency upgrade workflows.

If you belong to an organization that already has connected repositories, Agent P does not show the onboarding prompt. Go to the Repositories tab to view repositories already connected and configured for your organization.

For users who do not belong to an organization, the onboarding prompt is based on their personal GitHub App installations.

Onboard Repositories

  1. From the Agent P dashboard, select Onboard Repositories. You can also go directly to https://guide.sonatype.com/agent-p/setup.

  2. Search, sort, or filter the repositories as needed.

  3. Select the repositories that you want to onboard, or select Select All to select up to 500 matching repositories.

  4. Select Onboard.

  5. Review the number of selected repositories.

  6. Select Start Onboarding.

Agent P adds the repositories to the onboarding queue and begins creating setup pull requests.

To onboard more than 500 repositories, complete the current batch and then onboard the remaining repositories.

Monitor Onboarding

The onboarding page updates automatically as repositories are processed.

Status

Description

Queued

The repository is waiting to be processed.

In Progress

Agent P is creating the setup pull request.

Setup PR Opened

Agent P created the setup pull request.

Skipped

The repository already contains the required configuration files.

Failed

Agent P could not create the setup pull request.

After processing completes:

  • Review repositories with the Setup PR Opened, Skipped, or Failed status.

  • For each Setup PR Opened repository, review and merge the setup pull request. The setup pull request adds .github/workflows/agp-workflow.yml. Agent P attempts to merge the pull request automatically when repository rules allow it. If branch protection or other merge requirements prevent automatic merging, merge the pull request manually.

  • Select Onboard More to onboard another batch.

A repository is ready to configure after its setup pull request is merged.

Troubleshoot Onboarding

Symptom

Likely cause

What to do

Failed - could not create setup PR

Organization or repository settings block GitHub Actions from creating pull requests.

Enable Allow GitHub Actions to create and approve pull requests at the required organization and repository levels.

Failed - could not create setup PR

The GitHub App does not have the Workflows permission required to write files under .github/workflows/.

Re-authorize the GitHub App and grant the required Workflows permission.

Failed - could not create setup PR

The default branch cannot be resolved, or the repository is archived.

Verify that the repository has a default branch and is not archived.

Setup PR Opened, but the PR does not merge

Branch protection or another merge requirement prevents automatic merging.

Review and merge the setup pull request manually, or configure an appropriate exception according to your organization's policies.

agp job is skipped

The repository is paused in Guide, or the Guide gate cannot authorize the run.

If the repository is paused, resume it in Guide. Review the gate job for the reason the run did not proceed.

Configure Default Settings

Organization owners can define default settings for all repositories connected to Agent P. You can override these settings for individual repositories when needed.

To configure the default settings:

  1. From the Agent P dashboard, select Default Configuration.

  2. Configure the required settings in the following sections:

    • Feature Defaults: Control pull request creation, validation gates, security-only upgrades, dry runs, and automatic merging.

    • Setup: Add commands that run before the main Agent P process, such as installing required tools.

    • Build: Select the Java Development Kit (JDK) version used to build the project.

    • Validation: Configure validation commands, breaking-change commands, and the validation timeout.

    • Pull Requests: Define labels, reviewers, title and body templates, branch naming, and whether pull requests are created as drafts.

    • Auto Merge: Select the merge method used for automatically merged pull requests.

    • Limits: Control how many pull requests Agent P can create and how long it waits before proposing upgrades. These settings can cause Agent P to create fewer pull requests than expected.

    • Ignore: Exclude specific packages or file paths from upgrade processing.

    • General: Configure options such as skipping major-version upgrades and applying run-level labels.

    • Projects (Monorepo): Add project-specific settings for repositories that contain multiple buildable projects.

  3. Save the configuration.

For details about each setting, see Agent P Default Configuration Settings.

Repository-specific settings override organization defaults only for the fields configured at the repository level.

Configure Repository-Specific Settings

Use repository-specific settings when a repository requires configuration that differs from the organization defaults.

  1. From the Agent P dashboard, select the Repositories tab.

  2. Search and select the repository you want to configure, then select the Configure option.

  3. Update the required settings and save your changes.

Settings that you do not override continue to inherit the organization defaults.

Start Your First Agent P Run

After the setup workflow is present on the default branch, start the first Agent P run from GitHub

  1. In GitHub, open the repository and select the Actions tab.

  2. In the left navigation pane, select the Sonatype Guide - Agent P workflow.

  3. Verify that the default branch is selected. Leave workflow inputs at their defaults unless you have a specific reason to change them.

  4. Select Run workflow to start the run.

The workflow includes a gate job and an agp job. The gate determines whether Agent P should proceed and retrieves the applicable configuration. The agp job runs only when the gate directs it to run. A skipped agp job can therefore be expected when a repository is paused or the gate cannot authorize the run.

A successful run does not guarantee that Agent P creates a pull request. Agent P may find no eligible upgrades, validation may reject proposed upgrades, or configured limits and wait periods may prevent pull request creation.

Scheduled Runs

The onboarding workflow runs once per day by default. The schedule is defined in .github/workflows/agp-workflow.yml, rather than in the centrally governed Agent P configuration. If a scheduled run and a manually dispatched run overlap, runs queue instead of canceling one another.

Manage Repositories

The Agent P dashboard lets you monitor repository status, manage connected repositories, and review Agent P activity.

Repository Statuses

Status

Meaning / action

Disconnected

The repository is no longer connected to Agent P. Reconnect it before attempting to run Agent P.

Paused

Agent P is temporarily disabled for the repository. Resume the repository to allow runs

Needs attention

Agent P detected a condition that requires review. Open the repository details for the reported issue.

Missing Configuration

Required Agent P setup is not detected. Review the repository setup and workflow state.

Active

Agent P is enabled for the repository.

Ready to Run

Setup is complete and the repository can run Agent P

Setup PR opened

A setup pull request is open. Review and merge it if it cannot merge automatically.

Pause a Repository

Pause a repository to temporarily stop Agent P from scanning for dependency upgrades.

  1. On the Repositories page, locate the repository.

  2. Select More options (the three-dot icon), then select Pause.

  3. Confirm the action.

The repository status changes to Paused.

To resume the repository, select More options and then select Resume.

Note

Pausing a repository preserves its configuration. Agent P does not run or create pull requests while the repository is paused.

Disconnect a Repository

To disconnect a repository from Agent P, complete the following steps:

  1. Delete the .github/workflows/agp-workflow.yml file from the repository.

  2. Open your GitHub App settings.

  3. Select the Sonatype GitHub App, then select Configure.

  4. Under Repository access, remove the repository from the list of selected repositories. To remove access to all repositories, revoke the GitHub App's access entirely.

You can reconnect the repository later by granting the Sonatype Guide GitHub App access to the repository and onboarding it again.

Add Repositories

You can add repositories to Agent P at any time after completing the initial setup.

  1. From the Agent P dashboard, select Manage Connections > GitHub.

  2. Connect the additional repositories from your GitHub organization.

  3. Go to Onboard Repositories.

  4. Select the newly connected repositories and complete onboarding.

The existing GitHub App installation and organization-level configuration are reused.