Content rules

A content rule says which coordinates an upstream is asked for. Rules keep an internal upstream out of requests for public artifacts, keep a slow upstream out of requests it can't answer, and keep your own group away from a public mirror.

The rules work the way repositories { content { } } works in Gradle, 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 is 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.

Add a rule

To add a rule, follow these steps:

1. Open the repository and go to Upstreams.
2. In the upstream's Content rules section, click New rule.
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.

A rule 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 has to match the whole value. A pattern that isn't a valid regular expression is refused when you add the rule.

Exclusive upstreams

An exclusive upstream is the only upstream asked for the coordinates that its include rules match. Every other upstream is left out of those requests, even one that's listed earlier and holds the same artifact. This is what exclusiveContent does in a Gradle build.

Use it when one group must come from one place. An internal upstream that's exclusive for com.example guarantees that a build gets your own artifacts from it and never from a public mirror that happens to publish the same coordinates.

To make an upstream exclusive, follow these steps:

1. Open the repository and go to Upstreams.
2. In the upstream's row, click Edit.
3. Expand Advanced and turn on Exclusive.
4. Click Save upstream.
5. Add at least one include rule to the upstream.

An exclusive upstream without include rules claims nothing, so it's asked the way any other upstream is. When more than one exclusive upstream claims a coordinate, they're asked 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 scope and match	The matching exclude... method
Exclusive upstream with include rules	exclusiveContent { forRepository { ... } filter { ... } }

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. Make the upstream exclusive as well, and no other upstream is asked for that group.

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).

Advanced

A rule is applied before the request is made, so an excluded coordinate is never sent 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.

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