BIMP policy describes an approved transition from the base image a repository uses to the image your organization wants it to use. It is both a decision and an action path: the same published mapping drives evaluation, impact review, remediation, reporting, and audit.
Policy concepts
Section titled “Policy concepts”| Concept | Purpose |
|---|---|
| Policy group | A governance set for every repository or a selected scope. |
| Phase | An ordered mapping layer from an internal or external source. |
| Mapping | A source, target, reason, and optional platform scope. |
| Draft | The editable state. Draft changes do not alter live evaluation. |
| Published version | The immutable policy snapshot used by live evaluation. |
A repository can be governed by an organization-wide group and scoped groups. BIMP resolves the applicable published phases and mapping chain centrally so the Repositories page, impact review, worker, API, and MCP reach the same decision.
Create a policy group
Section titled “Create a policy group”From Policy, choose Create policy group and provide a clear name. Decide whether the group:
- applies to all repositories; or
- applies only to selected repositories and tracked branches.
For a scoped group, use the repository assignment dialog to choose branches. Repositories you can see but cannot manage remain visible and disabled. This is intentional: visibility is not the same as permission to change scope.
The group header shows Draft whenever its editable policy differs from the published version. It shows Published only when no draft difference remains.
Add a mapping
Section titled “Add a mapping”Add the mapping to the phase where it should be evaluated. Enter:
- From image, the observed source image or supported wildcard expression.
- Target image, the exact approved destination.
- Platform, when the decision applies to one OCI operating system and architecture combination.
- Reason, a concise explanation of the organizational decision.
Targets are always exact. A phase cannot contain two draft mappings for the same normalized source image and platform scope.
Match source images with wildcards
Section titled “Match source images with wildcards”Source images support explicit * wildcards. The match covers the complete
normalized image reference:
| Source | Matches |
|---|---|
node |
The exact normalized node reference. |
node* |
Concrete Node references that begin with node. |
node:18-* |
Tags such as node:18-alpine. |
Every other character is literal. Use the narrowest expression that represents the decision you intend to own. A broad wildcard can be useful; it can also be very enthusiastic.
Use an advisory recommendation
Section titled “Use an advisory recommendation”When the Docker Hub integration is enabled, the mapping form can recommend a target for a recognised Docker Official Image. BIMP evaluates tag precision, variant, and optional platform information, then offers a pinned or floating target.
The recommendation is current upstream observation plus a version heuristic. It is not a publisher claim, a vulnerability result, or an automatic policy change. Open Why this match, inspect the evidence, and select the suggestion only when it fits your organization’s decision.
Work with phases
Section titled “Work with phases”Phases are evaluated in order. Use the phase settings menu to add, remove, or reorder phases. A later mapping can continue a transition chain from an earlier target; BIMP resolves the chain to one final destination for evaluation and impact review.
An internal phase is authored in BIMP. It can import draft mappings from CSV or
JSON and export its visible draft mappings as bimp-mappings.json.
An external phase reads bimp-mappings.json from a connected provider
repository, branch, and path. Connect source fetches and validates the file
before saving the source settings. Synced mappings are read-only in BIMP.
Disconnecting copies the current live mappings into draft internal mappings;
the published policy remains effective until you publish the draft.
Review draft changes
Section titled “Review draft changes”Draft work stays separate from live policy. Deleting a previously published mapping marks it Deleted from draft until publication, giving you a chance to revert it. Removing a live phase follows the same principle: it disappears from the draft editor but remains effective in the published version.
When changes are ready, choose Publish to open Review change impact. The review lists only artifacts affected by changed draft mappings. Check:
- repository and tracked branch;
- source artifact path;
- affected image;
- resolved recommended image; and
- the next remediation timing or absence of a routine.
The review is a dry-run snapshot. It does not change policy or create remediation work.
Publish policy
Section titled “Publish policy”Choose the appropriate result from the Publish menu:
- Publish makes the draft version live. Affected artifacts follow their assigned-team remediation policy and routine timing.
- Publish and remediate makes the draft live and queues immediate remediation for affected artifacts. A second confirmation protects against an accidental rush of pull requests.
If an authorised reviewer marks the publish as a security incident, immediate
remediation is the only publish path. BIMP records the incident state and adds
the bimp-security-incident provider label to created or upgraded remediation
pull or merge requests.
Existing active remediation for a changed mapping is refreshed where possible. BIMP does not requeue unrelated recommendations merely because they remain outdated under other, unchanged mappings.
Restore or inspect a version
Section titled “Restore or inspect a version”Published versions are immutable. Use version history to inspect the policy that governed an earlier decision or to restore its contents as a new draft. Restoration does not rewrite history; you still review and publish the resulting draft as a new version.
Operating checklist
Section titled “Operating checklist”- Keep policy group scope explicit.
- Prefer a narrow source match unless the broader rule is deliberate.
- Record a reason that another reviewer can understand later.
- Treat integration recommendations as input, not authority.
- Read the impact table before publishing.
- Use immediate remediation only when the timing is intentional.
Next, see how published decisions become work in Remediation and routines.