Skip to main content

Connect and Onboard Repositories

This guide explains how to connect Agent P to GitHub, onboard repositories, and start a run.

Before you begin:

  • Set and force your instance’s base URL before registering a GitHub App. The base URL is used in the GitHub App configuration and as the expected audience in OIDC tokens. See Enable Agent P for instructions.

  • Confirm that you have the Agent P Administrator role. See Agent P in Sonatype AI Developer.

Before you start

  • Open AI Developer using its configured base URL, not localhost or another address. The URL you use when registering the GitHub App is included in the app’s configuration.

  • In the same browser, sign in to GitHub as an owner of the organization or personal account that will own the app.

  • Confirm that GitHub Actions is enabled for your organization and the repositories you plan to onboard.

  • Confirm that each repository builds successfully in its existing CI environment.

Step 1: Create the GitHub App

Create one GitHub App for each organization. Agent P uses the app to access your repositories.

Important

Agent P recognizes only GitHub Apps registered at the Root Organization level. Register and install the app there so Agent P can discover its repositories.

  1. In AI Developer, go to Orgs and Policies > Root Organization > Source Control.

  2. Set Source Control Management System to GitHub.

  3. Under Authentication Method, select GitHub App (Recommended).

  4. Select Add GitHub App.

  5. In the Connect to GitHub dialog, choose an account type:

    • Organization Account: Enter the organization name exactly as it appears in the GitHub URL, such as github.com/your-org-name.

    • Personal Account.

  6. Select Register & Create GitHub App. Your browser opens GitHub with a prefilled app manifest.

  7. On GitHub’s Create GitHub App page, keep or change the app name, then select Create GitHub App. GitHub returns you to AI Developer, which stores the app credentials and opens the GitHub installation page.

The app is private, so only its owning account can install it. AI Developer configures the app’s webhook, permissions, and subscribed events automatically. GitHub generates and stores the webhook secret; you do not need to copy it.

Note

If you created a GitHub App for source control before Agent P was available, it may not have the permissions or events Agent P needs. Open Manage GitHub Apps and check the app’s status. If permissions are missing, a banner provides a link for an organization owner to update them on GitHub.

Step 2: Install the app

On GitHub’s installation page:

  1. Choose the account where you want to install the app.

  2. Choose Only select repositories and select the repositories Agent P can access, or choose All repositories.

  3. Select Install & Authorize.

GitHub returns you to AI Developer and displays the GitHub Setup Complete dialog. Select Done.

Note

If GitHub requires approval from an organization owner, the installation remains pending until the owner approves it in GitHub under Settings > Third-party Access > GitHub Apps. The organization’s repositories appear in Agent P after approval.

Check the connection

Open Manage GitHub Apps to check the app’s relay connection status.

Status

Meaning

Relay link OK (check icon)

The app is linked and receiving events.

Pending registration

The app was recently installed, and AI Developer is still registering it.

Retrying (N/10)

Registration failed. AI Developer is retrying automatically, up to 10 times.

Failed — re-register

All automatic retries failed. An hourly job will retry, or you can reconfigure the app.

Step 3: Confirm the installation is linked to Agent P

Linking is automatic. Your installation connects to Agent P either:

  • The installation is linked immediately if the user who installed the app in Step 2 is an Agent P administrator, or

  • It is linked the first time an Agent P administrator opens Agent P (Preview) > Add Repositories.

Open Add Repositories to see how many repositories are connected and ready for setup after you link the installation.

Note

The Connect GitHub App option under Grant GitHub access is for installing the app for the first time or changing which repositories it can access. You don’t need to select it to link an existing installation.

If repositories don’t appear, wait a few seconds and reload the page while GitHub processes the webhook. If they’re still missing, make sure you’re signed in as an Agent P administrator and that the app was registered with the root organization (see Step 1).

Step 4: Onboard repositories

Open Agent P (Preview) and go to Add Repositories. If no repositories have been onboarded, Agent P opens this page automatically.

  1. Review the repositories available from the linked GitHub App installation.

  2. Use the filter and sort controls to find repositories.

  3. Select the repositories to onboard. You can select up to 500 repositories at a time.

  4. Select Add repositories.

  5. In the confirmation dialog, optionally select Merge setup pull requests automatically after they are opened.

  6. Confirm your selection.

Agent P opens a setup pull request for each selected repository. The pull request adds the GitHub Actions workflow file .github/workflows/agp-workflow.yml. If you did not enable automatic merging, review and merge each setup pull request in GitHub.

Agent P skips repositories that already contain the workflow file and indicates that the workflow is present.

Repository statuses

Status

Meaning

Missing Configuration

The repository has not been onboarded and is available to onboard.

Setup PR opened

The repository is onboarded, but the setup pull request has not been merged.

Ready to Run

The setup pull request is merged, but the workflow has not run.

Active

The workflow is present and has run recently.

Needs attention

A previous run completed, but the workflow appears to be missing or the last run is stale.

Paused

An administrator paused the repository. Runs will not start until it is resumed.

Disconnected

The GitHub App installation was suspended or removed, or the repository was removed from the installation.

Step 5: Start your first run

When a repository’s status is Ready to Run, start a run from GitHub:

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

  2. In the left navigation, select the Sonatype Guide - Agent P workflow. This is the workflow name for both cloud and self-hosted AI Developer.

  3. Confirm that the default branch is selected. Keep the workflow inputs at their defaults unless you need to change them.

  4. Select Run workflow.

The workflow runs the gate job first. This job checks whether the run can proceed and fetches your configuration. The agp job then runs the analysis. After the first manual run, the workflow runs daily at a randomized time for each repository.

A successful run does not always open a pull request. Agent P may find no eligible upgrades, validation may reject an upgrade, or pull request limits may prevent a request from opening. Open the run in Agent P to see the results and any reasons a pull request was not created.

Run Agent P outside GitHub Actions

You can also run Agent P using either of these options:

  • The agp command-line tool — Authenticate with an AI Developer user token. Use --dry-run for local testing.

  • The Agent P Jenkins plugin — Add a pipeline step that runs the same container image.

These options require separate configuration. Configure environment variables for the CLI or commit an agp.yml file to the repository for the Jenkins plugin. They do not automatically fetch the governed configuration used by GitHub Actions. See Agent P Configuration Reference for details.

Manage connected repositories

On the Repositories tab of the Agent P dashboard, open a repository’s actions menu to:

  • Select Configure to edit repository-specific configuration.

  • Select Pause or Resume to stop or restart scheduled and on-demand runs. Pausing retains the repository configuration.

  • Select Disconnect to open a pull request that removes the Agent P workflow file. Review and merge the pull request to complete disconnection. To fully revoke access, also remove the repository from the GitHub App installation.

  • Select Open in GitHub to open the repository.