Content rules

A content rule says which coordinates an upstream may be asked for. Rules keep an internal repository from being asked for public artifacts, keep a slow upstream out of requests it can't answer, and keep a build from reaching a mirror that shouldn't hold your own group.

The semantics are the ones that Gradle uses in repositories { content { } }, so a rule that you already have in a Gradle build translates directly.

How rules are applied

For each request, Artifex decides whether an upstream may be asked:

• If the upstream has any include rules, it's asked only when the coordinate matches at least one of them.
• If the coordinate matches any exclude rule, the upstream isn't asked, even when an include rule matched.
• An upstream with no rules is asked for everything.

A rule is applied before the request is made, so an excluded coordinate costs nothing and never leaks the coordinate to that upstream.

A request that doesn't carry 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 would hide versions that the rule allows.

Add a rule

To add a rule, follow these steps:

1. Open the repository and go to Upstreams.
2. Open the upstream and go to Content rules.
3. Under Effect, select Include or Exclude.
4. Under Scope, select Group, Module, or Version.
5. Under Match, select Exact, Group and subgroups, or Regular expression.
6. In the Group field, enter the group, such as com.example.
7. For the module and version scopes, in the Module field, enter the artifact ID.
8. For the version scope, in the Version field, enter a version or a version range.
9. Click Add rule.

Adding or removing a rule forgets what the upstream remembered as missing, so the change takes effect on the next request.

To remove a rule, click Remove in its row.

Scopes

Scope	What it names	Fields
Group	Every artifact in a group	Group
Module	One artifact in a group	Group, Module
Version	One version of one artifact	Group, Module, Version

Matches

Match	Applies to	Behavior
Exact	Group, module, version	The value has to be equal to the pattern. For a version, a Maven version range such as [1.0,2.0) is accepted and matches any version in the range.
Group and 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 scope uses them, still have to be equal.
Regular expression	Group, module, version	The pattern is anchored at both ends, so it has to match the whole value. A pattern that isn't a valid regular expression is refused when you add the rule.

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 scope and match	The matching exclude... method

Examples

Keep your own group off a public mirror. On the Maven Central upstream, add an exclude rule with the group scope, the group and subgroups match, and the group com.example. Your own artifacts are then never requested from Central, and a build that asks for 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 scope, the group and subgroups match, and the group com.example. That upstream is then asked for nothing else.

Pin a legacy version to an old mirror. On the mirror, add an include rule with the version scope, the exact match, the group and module of the artifact, and the version range [,2.0).