Agent P Configuration Reference
This reference explains the settings on the Agent P configuration pages, including what each setting controls and its default behavior. The sections follow the order of the pages and use the labels shown in the product. You do not need to edit a configuration file.
Find the Configuration Pages
Page | How to get there | Who can change it |
|---|---|---|
Default Configuration | Agent P, Default Configuration tab. Appears once your organization has at least one connected repository. | Agent P Administrators. Other users see it locked, with Save governance settings and Download agp.yml hidden. |
Repo Configuration | Open a repository in Agent P and select the Repo Configuration tab, or use Configure in the dashboard's repository actions menu. | Agent P Administrators only. |
How the Pages Work Together
Every repository starts out following the Default Configuration.
On a repository's configuration page, change only the settings that need to differ for that repository. Inherit, or a blank field, keeps following the Default Configuration.
The repository configuration page shows grey placeholder text such as "Inherited: npm test" under a field you haven't overridden — that's the value currently in effect.
Reset to defaults removes every override for that repository at once. This cannot be undone.
After You Save
The Saved badge confirms that your changes were saved. They take effect on the next run; saving does not start a run.
Select Download agp.yml to see the configuration Agent P will actually use, as of your last save. Unsaved edits aren't included.
To see results, open the repository in Agent P and check its Runs tab.
If another user saves changes while you have the page open, Agent P asks you to reload the page and reapply your changes. Your changes are not overwritten or applied until you save them again.
Configure Agent P
For an initial setup, review these settings first:
Validation Gates: Turn On, then add your build and test commands under Validation > Commands. Validation Gates is Off by default, so without this, Agent P opens pull requests without checking that they build.
Max open PRs and Max PRs per run: Set limits that match your team’s review capacity.
Ignore > Packages: List packages that Agent P must not upgrade.
Dry Run: keep it Off when you want real pull requests opened.
Save. The button reads Save on a repository's page, or Save governance settings on the Default Configuration page.
Settings you can leave blank
These settings are saved but currently have no effect:
Setting | Section |
|---|---|
Timeout | Validation |
Title template, Body template, Branch template | Pull requests |
Draft PRs | Pull requests |
Wait period between PRs (Major, Minor, Patch) | Limits |
Labels | General |
How the controls work
Control | How to use it |
|---|---|
Switch (Default Configuration) | On or Off. Always saved. |
Three-way list | Inherit, On, or Off (labeled Default or Inherit default on the Default Configuration page, since there's nothing to inherit from there). |
Text box | Type a value. Blank means "not set." |
Number box | Whole numbers only. Blank means "not set." |
Add-list | Type a value, then press Enter (or select the add icon). Leaving the box also adds it. Select the x on a value to remove it. |
Dropdown | Pick from the list. |
A few rules apply across every field on a repository's configuration page:
A list you fill in replaces the inherited list — it doesn't add to it. If the Default Configuration ignores
left-padandrequest, and you addmomenton a repository, that repository ignores onlymoment. Enter all three to keep all three.To undo an override, change the field back to Inherit (or clear it) and save — the repository follows the Default Configuration again.
You can't blank out a value you only inherit. To remove an inherited value for one repository, an Agent P Administrator needs to change the Default Configuration, or set an explicit different value on that repository.
Time values are a number plus one letter:
ddays,hhours,mminutes,sseconds (for example45s,30m,3h,7d). A value like1h30mor a decimal like1.5his not valid.
Feature defaults
The first section — Feature defaults on the Default Configuration page, Feature overrides on a repository's page.
Setting | What it does | Default |
|---|---|---|
PR Creation | Agent P opens pull requests for the fixes it finds. | On |
Validation Gates | Runs your build and test commands before any pull request is created. | Off |
Security Only (Beta) | Processes only packages with a known vulnerability. Pull request limits still apply. | Off |
Dry Run | Testing mode: Agent P analyzes and reports, but creates no branches, commits, or pull requests. | Off |
Auto Merge | Asks GitHub to merge each eligible pull request automatically once its required checks pass. | Off |
Note
PR Creation and your workflow interact the standard workflow Agent P generates always requests pull requests. To stop pull requests from opening,
Setup Commands
Commands that prepare the repository before the main Agent P analysis runs — for example, installing toolchains. They run once per run, in order, from the repository root. If one fails, the whole run stops.
Enter one command per entry.
Agent P does not validate commands when you save. An invalid command is saved and fails when the workflow runs. Test commands in a terminal before adding them.
Example:
npm ci --ignore-scripts.
See Command rules below for what's allowed in a command entry.
Build Settings
Setting | What it does | Default |
|---|---|---|
Java version | Chooses the JDK used for Maven builds (dependency updates, and | JDK 21 |
If the selected JDK is unavailable in the Agent P container, Agent P uses JDK 21 and displays a warning.
Validation Settings
These commands run only when Validation Gates is On, with one exception: a project with its own Validation override On and its own commands (see Projects).
Setting | What it does |
|---|---|
Commands | Commands that validate a proposed upgrade before a pull request opens. All must pass; they run in order and stop at the first failure, in each affected project's folder. |
Breaking-change commands | Extra commands run only when Agent P detects a breaking change — for heavier checks on riskier upgrades. |
Validation Settings Behavior
Validation Gates | Commands | Result |
|---|---|---|
Off | any | No validation runs, except for a project with its own Validation override On and its own commands. |
On | filled in | Your commands run before each pull request. |
On | empty | Agent P runs a basic build check for the detected ecosystem instead of your tests. Always fill in Commands if you want your own tests to run. |
When Validation Gates is on and no commands are configured, Agent P runs a basic check for the detected ecosystem: npm (npm run build — your repository needs a build script, or every upgrade fails), Maven (compile), Gradle (classes), .NET (dotnet build), Go (go build ./...), Python (pip check — checks installed dependencies; builds nothing).
Note
Breaking-change upgrades are skipped by default. Agent P skips an upgrade it knows includes a breaking change unless all three are true: Validation Gates is On and Breaking-change commands has at least one entry.
Example commands by ecosystem
Ecosystem | Commands |
|---|---|
npm |
|
Maven |
|
Python |
|
Go |
|
.NET |
|
Command rules
These rules apply to Setup, Validation, and Breaking-change commands, including commands configured for individual projects:
Don't chain commands with
&&,||,;,|,>, or backticks. Setup rejects such an entry and stops the run; for Validation, the extra text is passed as arguments to the first program, so the second command silently never runs. Use one entry per command.Start with a program Agent P recognizes:
npm,yarn,pnpm,bun,mvn,gradle,./mvnw,./gradlew,mvnw.cmd,gradlew.bat,node,deno,python,python3,pip,pip3,poetry,uv,pipenv,pytest,dotnet,go,git.A script path such as
./scripts/check.shis not allowed — call it through an npm script or Maven goal instead (for example,npm run check).Setup commands (not Validation) also accept other plain program names, such as
make.Secrets from your workflow (
NPM_TOKEN,GITHUB_TOKEN,GH_TOKEN, AWS keys, and anything ending in_TOKEN,_SECRET,_PASSWORD,_API_KEY, or_CREDENTIALS) are not passed to these commands. There are two exceptions:ANTHROPIC_API_KEYis passed through, and custom-named variables that don’t match those suffixes are also passed through. Don’t rely on a custom variable name alone to keep a secret out of these commands.Use quotes for a value containing spaces, for example
git config user.name "agp bot".
Pull Requests
Setting | What it does | Default |
|---|---|---|
Labels | Labels applied to every Agent P pull request, replacing the built-in default list. Agent P always adds its own classification label (security, policy, or routine update) regardless of this setting. |
|
Reviewers | GitHub usernames (or | none |
Title template, Body template, Branch template | Currently have no effect — Agent P writes its own titles, bodies, and branch names. | — |
Draft PRs | Currently has no effect — pull requests always open as normal pull requests. | Off |
Reviewers: a requested team must belong to the same GitHub organization as the repository, and your GitHub App needs organization "Members: read" access to request a team. Without it, Agent P doesn't request the team and logs an error. GitHub allows at most 15 reviewers per pull request.
Auto Merge
Matters only when Auto Merge is On.
Setting | What it does | Default |
|---|---|---|
Merge method | Strategy used when auto-merging: squash, merge, or rebase. | squash |
GitHub only — other source control providers log that auto-merge was skipped.
GitHub must allow auto-merge on the repository, and your chosen method. When GitHub refuses, Agent P comments on the pull request with the reason.
Pair this with branch protection that requires passing checks, so a pull request only merges after checks pass.
A pull request that includes an AI repair is never auto-merged — it always needs human review.
Pull Request Limits
Setting | What it does | Default |
|---|---|---|
Max open PRs | Most Agent P pull requests allowed open at once. 0 means no new pull requests. | 5 |
Max PRs per run | Most pull requests a single run may create. | 10 |
Wait period between PRs (Major, Minor, Patch) | Currently has no effect. | — |
Both limits apply together: a run opens at most the smaller of (Max open PRs minus PRs already open) and Max PRs per run. Both fields require whole numbers — 0 or more.
Ignore Settings
Use this to permanently decline specific upgrades.
Setting | What it does |
|---|---|
Packages | Package names Agent P should never upgrade. Not applied while Security Only (Beta) is On. |
Paths | Folder patterns Agent P should never scan for projects. |
Packages
Enter | It ignores |
|---|---|
| The package named |
| That exact scoped npm package (wildcards like |
| That exact Maven artifact ( |
| Every Maven artifact in exactly that group (sub-groups are not included). |
Names are case-sensitive. The * wildcard works only as groupId:* at the end — any other use matches nothing and shows a warning.
Paths
Patterns match a folder path starting from the repository root. A match ignores that folder and everything below it.
Enter | It ignores |
|---|---|
| The |
| Any |
| Every folder directly inside |
* matches within one folder name; ** matches any number of folders.
Note
To skip one project only for validation but still receive upgrade pull requests for it, use that project's own Validation override set to Off instead (see Projects). Ignore > Paths removes the project entirely, so it gets no upgrade pull requests either.
General Settings
Setting | What it does | Default |
|---|---|---|
Skip major versions | Agent P picks the highest available upgrade within your current major version. If only a major-version upgrade exists, the package is skipped — unless your current version is vulnerable and no smaller safe upgrade exists, in which case the major upgrade is still proposed. | Off |
Labels | Currently has no effect. | — |
Projects (Monorepos)
Use this section when a repository contains multiple buildable projects that require different settings. Each project has its own card. Select Add project to add a card.
A card is dropped automatically (with no warning) if it's saved without a Name or Path. Two cards with the same name collapse into the last one saved.
Setting | What it does | Required |
|---|---|---|
Name | A label for the project. Also how an inherited project is matched on a repository's page. | Yes |
Path | The project's folder from the repository root, with no leading | Yes |
Ecosystem | The kind of project at that path — only needed when one folder contains more than one (for example, both | No (auto-detected) |
Skip major versions | Overrides the General setting, for this project only. | No |
Validation override | Overrides validation for this project only. | No |
Validation commands | Commands for this project, run in its own folder. | No |
How validation is chosen for each project
Project setting | Result |
|---|---|
Validation override Off | Never validated, regardless of the global settings. |
On, with commands | Those commands run, even if Validation Gates is Off organization-wide. |
On, with no commands | Runs the basic check for the ecosystem — does not fall back to the global Commands. |
No card for this project | Uses the global Commands, if Validation Gates is On and they're filled in. |
On a repository's configuration page, a project defined in the Default Configuration appears as a read-only "Inherited" card. To change it, add a card with the same Name — yours completely replaces it, including Path, so fill in every field again.