P4A DocumentationPublishing a ruleset
Publish an approved ruleset to your Anypoint Exchange from P4A and, optionally, add it to an API Governance profile.
Overview
An approved ruleset in the P4A catalog can be published to the Anypoint Exchange of your own organization. API Governance reads rulesets from Exchange, so this is the step that makes a ruleset usable for your APIs. P4A does it through a registered Anypoint connection, so you don't need the Anypoint CLI. You can also add the new ruleset to a governance profile in the same step.
Approved, published rulesets can be published to Exchange by anyone. While a ruleset is under review, only its invited reviewers (including its submitter) and platform admins can publish it, so they can try it before it's approved. Everyone else sees a disabled Publish to Exchange button with a tooltip that says so. A rejected ruleset can't be published.
Before you start
- A registered Anypoint connection. See Connecting your Anypoint ORG. The connection must be allowed to publish to Exchange in the business group you pick.
- API Governance permissions, for governance profiles. Publishing to Exchange doesn't need them. Creating a profile or adding rulesets to one does. See Permissions.
- A ruleset to publish. Write one with Authoring a ruleset, or open one from the Rulesets catalog.
Permissions
P4A acts as your Connected App, so the Connected App needs these permissions, not your user. Assign each one in the business group you pick in the dialog: the one you publish into, or the one that owns the profile.
| What you do in P4A | Anypoint permission |
|---|---|
| Publish or unpublish a ruleset | Exchange Contributor (with Exchange Creator and Exchange Viewer, as for policies). See Connecting your Anypoint ORG. |
| See the list of existing profiles | API Governance: Governance Viewer or Governance Administrator |
| Create a profile | API Governance: Governance Administrator |
| Add rulesets to an existing profile | API Governance: Governance Administrator. P4A reads the profile first so it can keep its current rulesets, which this permission also covers. |
Governance Viewer alone can't change profiles. Without it, P4A can't list the profiles and asks you for a profile ID instead. Adding to that profile still needs Governance Administrator. MuleSoft's own rulesets are public in Exchange, so referencing their GAVs needs no extra Exchange permission.
For what each permission allows in Anypoint, see Getting Started with Anypoint API Governance and CLI commands for API Governance.
Publishing
Open the ruleset's detail page and click Publish to Exchange. A dialog opens.
Fields in the dialog
- Workspace and Anypoint Connection: where the credentials come from. The workspace controls which shared connections you can pick. See Using workspaces.
- Target business groups: the Anypoint business groups to publish into. Each one you select becomes its own publish, and they run in parallel.
- Exchange asset ID: the asset's identifier in Exchange, lowercase letters, digits and hyphens. It's prefilled from the ruleset's
exchange.jsonor its name. Leave it blank to use the ruleset's default. - Version: optional, in the form
1.2.3(three numbers, novprefix). Leave it blank to use the version in the ruleset'sexchange.json, or1.0.0when there isn't one. - Source ref: optional branch, tag, or commit to publish from. It defaults to the ruleset's own ref.
- Apply to a governance profile: optional. See Adding it to a governance profile.
Exchange versions are immutable. You can't overwrite a version that already exists. To publish a change, give the ruleset a new version, either in the dialog or in its exchange.json. Publishing a version that already exists fails with a message telling you to bump the version.
If deployments are paused, the dialog shows a banner and the button stays disabled until they resume.
Following the job
After you click Publish, the ruleset's detail page shows a Deployments card with one row per business group. Each row shows the status, streams the build log while it runs, and offers Open in Exchange once it's published. You're also notified of the outcome. You can see the same rows on the connection's page, and with list_deployments and get_deployment over MCP. Once it's live, the ruleset also appears on the Rulesets tab of the workspace whose connection you used. See Using workspaces.
Publishing from an agent works the same way: deploy_ruleset asks you to confirm, then returns one deployment ID per business group. Track each with get_deployment. See the MCP tools reference.
Adding it to a governance profile
A governance profile decides which APIs a ruleset checks. Tick Apply to a governance profile to do this as part of the publish:
| Option | What it does |
|---|---|
| Create | Makes a new profile with the Profile name you give. Set its Filter criteria the same way as in Anypoint: under General, tick the API Types it governs (REST API, AsyncAPI, HTTP API, Agent, MCP, gRPC; none ticked means every type) and add optional Tags and Categories (name:value). Under API Instance, choose All APIs, Include only APIs with instances (then an Environment type: Any, Production or Sandbox), or Only APIs without instances. |
| Update | Adds the ruleset to an existing profile. Pick the profile from the list of the first target business group's profiles. If P4A can't list them (for example the connection lacks API Governance access), enter the profile ID instead. The profile keeps the rulesets it already has. |
| Notifications | Optional. Tick API contact and API publisher, or list Other recipients by email, to be emailed when an API fails conformance. See Notifications. |
| Additional rulesets | Optional group/asset/version entries to attach alongside yours, for example a MuleSoft ruleset's GAV. See Rulesets in P4A. |
The profile step runs after the upload. If it fails, for example because the connection can't manage profiles, the ruleset stays published, because the asset is already in Exchange and can't be re-uploaded. The row shows governance profile not applied with the reason on hover. Fix the permission, then use Add to profile on that row of the Deployments card, or add the ruleset to the profile in Anypoint. When it works, the row shows the profile name.
Adding a ruleset that's already published
You don't need to publish again to add a ruleset to a profile. You can start from:
- Add to governance profile on a MuleSoft ruleset's page, next to its GAV, or
- Add to profile on a published row of the Deployments card of a ruleset you've published.
From the GAV block, pick the workspace, connection and the business group that owns the profile. From a deployment row, they're fixed to where that version was published, and shown read-only. If that connection or business group is no longer available to you, the dialog says so and you can't submit. Then either choose an existing profile or create a new one. The Rulesets field is prefilled with the ruleset's group/asset/version and accepts up to 20 comma-separated entries. Nothing is uploaded to Exchange. You're told when the profile is updated, or why it failed.
From an agent, list_governance_profiles lists a business group's profiles and attach_ruleset_to_profile adds the rulesets. It asks you to confirm first. Adding to a profile counts toward your daily deploy limit.
Notifications
API Governance can email people when an API fails the profile's rules. In the Notifications box, choose who:
- API contact: the contact on the API's Exchange page.
- API publisher: whoever published the API.
- Other recipients: up to 20 email addresses, comma separated.
When you create a profile and leave the box empty, it sends no notifications. When you add to an existing profile and leave it empty, the profile keeps its current notifications. If you set any recipient, it replaces the profile's recipient list. To change other notification settings, edit the profile in Anypoint API Governance.
Profile rules are evaluated by API Governance, not P4A. For criteria, notifications and how conformance is reported, see Creating Governance Profiles and Finding and Fixing Conformance Issues.
Unpublishing
Use Unpublish on a deployment row to remove the ruleset version from Exchange. P4A deletes the version and, when Exchange won't allow a delete, deprecates it instead. The row then shows as deleted.
If a governance profile still uses the ruleset, the unpublish fails. Remove the ruleset from those profiles in Anypoint first, then try again.
Troubleshooting
| Message | Cause | Fix |
|---|---|---|
| Version already exists, bump the version | That version is already in Exchange for the asset ID | Publish again with a new Version. |
| Asset ID or version rejected in the dialog | The asset ID has uppercase letters or other characters, or the version isn't 1.2.3 | Use lowercase letters, digits and hyphens, and three dot-separated numbers. |
| Ruleset does not conform to the dialect | The profile fails validation | Fix the YAML. See Authoring a ruleset and run an authoritative validate_ruleset. |
| Unauthorized or forbidden | The connection can't publish in that business group | Check the Connected App's Exchange scopes and business group access. See Connecting your Anypoint ORG. |
| Cannot unpublish: in use by a governance profile | A profile references the ruleset | Remove it from the profile, then unpublish. |
| Governance profile not applied | The profile step failed after a good upload | Check the permissions and the profile name or ID, then use Add to profile on the row. |
| Profile list shows a profile ID field | P4A couldn't list the business group's profiles, or there are none | Give the Connected App Governance Viewer (or Governance Administrator) in that business group, or enter the profile ID from Anypoint. |
| Unauthorized or forbidden when adding to a profile | The Connected App lacks Governance Administrator in the profile's business group | Assign it. See Permissions. |
exchange.json is not valid JSON, or its version is not MAJOR.MINOR.PATCH | The ruleset's exchange.json can't be read, or its version has a v prefix or a suffix | Fix the file in the repository, or set Version in the dialog to override it. |
| A validation or publish fails with no rule messages, only a sign-in, network or timeout error | The Anypoint CLI couldn't reach Anypoint with the connection, so it never checked the ruleset | Check the connection's credentials and scopes, then try again. For the CLI's own error messages, see Troubleshooting CLI commands. |
| Publish button disabled | The ruleset isn't approved yet and you aren't one of its reviewers, or deployments are paused | Wait for approval or for the pause to end. |