Skip to main content

Enable Agent P

Agent P is included with Sonatype AI Developer. On a self-hosted instance, install an AI Developer license first. See Getting Started with AI Developer.

Before connecting GitHub, an administrator must enable the SCM relay integration and set the instance’s base URL. The following steps require the Edit System Configuration and Users permission, which is included in the System Administrator role.

Set and force the instance base URL

Set and force your instance’s base URL before creating the GitHub App or onboarding repositories. Agent P uses this URL:

  • In the GitHub App configuration, including its home page, callback, and setup URLs.

  • As the expected audience in the OIDC tokens sent by your CI environment. Your instance rejects tokens with a different audience.

Set and force the base URL with the REST API:

curl -u admin:admin123 -X PUT -H 'Content-Type: application/json' \\
  -d '{"baseUrl":"https://your-iq-server.example.com/","forceBaseUrl":true}' \\
  http://localhost:8070/api/v2/config

Forcing the base URL ensures the GitHub App uses the correct public address. Without this setting, the instance may use the address in your browser when you register the app. If you access the product through localhost or an internal hostname, GitHub may be configured to send users to an address they cannot reach.

Note

Changing the base URL after onboarding repositories breaks their Agent P workflows. Each workflow uses the base URL that was configured when the repository was onboarded as its token audience. Your instance rejects tokens addressed to a different URL. Set the correct base URL before connecting GitHub, and do not change it after onboarding repositories.

When a GitHub App gets a webhook

A GitHub App only receives a webhook and so only sends Agent P the events it needs (installations, pull request updates, CI results). if it's registered on the Root Organization after AI Developer is active on your instance. This is why setting your base URL correctly before you create the App matters, and it's also why an App created earlier, before AI Developer was active, won't work for Agent P even after you enable AI Developer.

Your instance can't retroactively add a webhook to an existing App. If you have an App that predates AI Developer, delete it and register a new one under Orgs and Policies > Root Organization > Source Control. The Agent P setup page shows a notice when it detects an App like this.

Confirm Agent P is available

After your license includes AI Developer directly or through the opt-in and you complete both setup steps, Agent P (Preview) appears in the AI Developer navigation.

If Agent P does not appear:

  • Confirm that your license includes AI Developer or that someone has accepted the AI Developer opt-in terms. See Agent P in Sonatype AI Developer.

  • Confirm that your instance uses an external PostgreSQL database. AI Developer and Agent P are not available with the embedded H2 database.

  • Confirm the Agent P launch feature hasn't been turned off for your instance. An administrator can turn it back on with POST /api/v2/config/features/iqAgentPLaunched.