Content rules
A content rule says which Maven coordinates are requested from an upstream. Use rules to prevent Artifex from requesting public artifacts from an internal upstream, artifacts from an upstream that doesn't host them, and your own group from a public upstream.
The rules work like Gradle repository content filters, so a rule that you already have in a Gradle build translates directly.
How rules are applied
For each request, Artifex decides whether to request from an upstream:
- If the upstream has any include rules, Artifex requests from it only when the coordinate matches at least one of them.
- If the coordinate matches any exclude rule, Artifex doesn't request from the upstream, even when an include rule matched.
- Artifex requests everything from an upstream that has no rules.
Add a rule
To add a rule, follow these steps:
Open the repository and go to Upstreams.
In the upstream's row, click New content rule. When the upstream already has rules, click the rule count to open them, and then click New content rule.
Under Effect, select Request only from this upstream or Never request from this upstream.
For Resolution context, select A group, One module in a group, or One version of a module.
Under How the group is matched, select Exactly this group, This group and its subgroups, or A regular expression.
In the Group field, enter the group, such as
com.example.For a module or a version, in the Module field, enter the Maven artifact ID or Gradle module name.
For a version, in the Version field, enter a version or a version range.
Click Add rule.
A rule takes effect on the next request.
To see an upstream's rules, click the rule count in its row. To remove a rule, click Remove beside it.
Resolution context
| Choice | What it names | Fields |
|---|---|---|
| A group | Every artifact in a group | Group |
| One module in a group | One artifact in a group | Group, Module |
| One version of a module | One version of one artifact | Group, Module, Version |
How the group is matched
| Choice | Applies to | Behavior |
|---|---|---|
| Exactly this group | Group, module, version | The value must equal the pattern. For a version, a Maven version range such as [1.0,2.0) is accepted and matches any version in the range. |
| This group and its subgroups | Group | Matches the group and every group under it. com.example matches com.example and com.example.tools. The module and version parts, if the rule uses them, must still be equal. |
| A regular expression | Group, module, version | The pattern must match the whole value. A pattern is rejected when you add the rule if it isn't a valid regular expression, is longer than 200 characters, or repeats a group, such as (a+)+, because such a pattern can cause catastrophic backtracking. |
Exclusive content rules
An exclusive content rule makes the repository itself the exclusive source for matching coordinates. Artifex never requests them from an upstream, so a build that requests a version the repository doesn't hold gets a not-found response immediately. Use this rule for your own group so that your artifacts are never requested from a public upstream.
To add one, follow these steps:
- Open the repository and go to Upstreams.
- Under Exclusive content rules, click Add exclusive rule.
- For Resolution context, select A group, One module in a group, or One version of a module, and fill in the fields as for a content rule.
- Click Add rule.
To remove an exclusive content rule, click Remove in its row.
Exclusive upstreams
An exclusive upstream is the exclusive source for coordinates that match its include rules. Artifex doesn't request those coordinates from any other upstream, even an earlier upstream that holds the same artifact.
Use it when one group must come from one upstream. An internal upstream that's exclusive for com.example prevents dependency confusion: a build gets your own artifacts from it and never from a public upstream that publishes the same coordinates.
To make an upstream exclusive, follow these steps:
- Open the repository and go to Upstreams.
- In the upstream's row, click Edit.
- Turn on Exclusive.
- Click Save upstream.
- Add at least one include rule to the upstream.
An exclusive upstream without include rules behaves like any other upstream. When more than one exclusive upstream matches a coordinate, they're requested in their listed order. Exclude rules still apply.
The Gradle equivalents
| Rule in Artifex | Gradle |
|---|---|
| Include, group, exact | includeGroup("com.example") |
| Include, group, group and subgroups | includeGroupAndSubgroups("com.example") |
| Include, group, regular expression | includeGroupByRegex("com\\.example\\..*") |
| Include, module, exact | includeModule("com.example", "lib") |
| Include, module, regular expression | includeModuleByRegex("com\\.example", "lib-.*") |
| Include, version, exact | includeVersion("com.example", "lib", "1.0") |
| Include, version, regular expression | includeVersionByRegex("com\\.example", "lib", "1\\..*") |
| Exclude, any resolution context and match | The matching exclude... method |
| Exclusive upstream with include rules | exclusiveContent { forRepository { ... } filter { ... } } |
| Exclusive content rule | The same, pointed at the Artifex repository |
Examples
Exclude your own group from a public upstream. On the Maven Central upstream, add an exclude rule with the group resolution context, the group and subgroups match, and the group com.example. Your own artifacts are then never requested from Central, and a build that requests one gets it from the repository itself or not at all.
Send one group to an internal upstream. On the internal upstream, add an include rule with the group resolution context, the group and subgroups match, and the group com.example. Artifex then requests nothing else from that upstream. Make the upstream exclusive as well, and no other upstream is requested for that group.
Pin an earlier version to a separate upstream. On that upstream, add an include rule with the version resolution context, the exact match, the group and module of the artifact, and the version range [,2.0).
Advanced
A request that doesn't include every part of a coordinate, such as artifact-level metadata checked against a version rule, matches. The request might still lead to a matching version, and refusing it can hide versions that the rule allows.