Instructions for coding agents

You are a coding agent, and you have been asked to configure an existing Maven or Gradle build to use a repository that already exists in CodeSoh Artifex. The prompt that brought you here gives the repository name and its Maven repository URL. The API is at the same origin as the Maven repository URL, under /api/v1/, with its document at /api/v1/openapi.json.

This page tells you what to achieve and how to report it. The person who owns the build reads Configure a build to use Artifex with AI.

Read this site as Markdown

Every page of this site is served as Markdown at its address with .md appended, such as https://docs.soh.gg/artifex/agent-guide.md. The list of pages is at https://docs.soh.gg/llms.txt.

Get two tokens first

You need two tokens. Ask for both before you read the build because nothing else that you do needs the person's attention.

Read Use the API, and then start the device flow twice:

1. One for you, with Manage access. Give the person the verificationUrl to open. The code is already in the URL, so don't ask them to enter it. They approve a token with Manage access while you wait. Use this token for every API call in this task and for nothing else.
2. One for the build, with Write access. Start the flow again under a name that identifies the build, such as the build's own name. Ask the person to approve Write access to this repository only. Put this token in the build.

Never put your Manage token in the build. A build resolves and publishes, which Write covers. A Manage token in a build file, properties file, or continuous integration (CI) variable can also change the repository settings, add upstreams, and share the repository with other people.

Send a User-Agent header that names your tool on every request. Requests without this header, or with a bare library default, can be refused before they reach Artifex.

The goal

After the configuration, the build resolves its dependencies and publishes through the Artifex repository. In every other way, it behaves as it did before: the same artifacts resolve from the same sources, in the same order of preference, with the same restrictions on which repository serves each group.

Add an Artifex upstream for every repository that supplied the build's project dependencies. Preserve the configured order, credentials, and exclusivity. Translate Gradle repository content filters into Artifex content rules. Then replace the build's project dependency repositories with the one Artifex URL and use the build token as the password.

Rules

• Migrate project dependency repositories. A build can have several resolution contexts. Gradle has pluginManagement, dependencyResolutionManagement, each project's buildscript, and each project's repositories. Maven has repositories and pluginRepositories. Migrate only the repositories that resolve project dependencies. Leave plugin and buildscript repositories unchanged. Preserve Maven dependency scope, such as compile, runtime, and test; repository configuration must not change it. Don't try to reproduce a coordinate that different resolution contexts fetched from different places. Artifex can't represent that distinction, and this task doesn't ask for it.
• Use presets before remote upstream URLs. Artifex provides presets for Maven Central, the Gradle Plugin Portal, Google Maven, Minecraft Libraries, NeoForged, Minecraft Forge, FabricMC, JitPack, and Sonatype Snapshots. GET /api/v1/presets lists them. When the build uses a repository that has a preset, add that preset by its API slug. Don't add content rules because the preset carries them. Add a remote upstream only for a repository that isn't a preset.
• Preserve behavior instead of choosing a convenient approximation. Before you change the build, record what it resolves and from where. After the change, resolve again and compare. A dependency that comes from a different source or no longer resolves is a regression that you must fix. Report anything that Artifex can't reproduce; don't approximate it.
• Retain existing publication repositories. If the build publishes to a repository elsewhere, leave that repository in place and add Artifex as a second publication repository. Don't remove or replace the existing one. A file:// publication repository isn't a source of dependencies and needs no upstream.
• Add a publication repository as an upstream when the build also resolves from it. Configure the remote upstream with its credentials so that the versions that it stores continue to resolve.
• Name build entries after Artifex. Wherever you introduce a name for the repository or its credentials, use artifex: the Gradle repository name, the Maven server ID, variables, environment variables, and property keys such as artifexUsername and artifexPassword. Don't use codesoh or a generic name.
• Touch nothing else. Don't change versions, plugins, or settings that aren't related to repositories.

Report when you are done

Tell the person exactly what you did, in the order that you did it, and what changed. For every step, say how they can do the same thing on the Artifex pages and link to the page that describes it:

What you did	Where they do it themselves
Obtained your own token and the build's token	Tokens
Changed a repository's settings	Repositories
Added, ordered, or changed an upstream	Upstream repositories
Added a content rule or made an upstream exclusive	Content rules

List every build file that you changed and what changed in it. State what you compared before and after, and the result. Put anything that you couldn't reproduce at the start of the report, along with what you did instead.

Helpful information

The remaining information covers common Gradle and Maven builds. It might not fit the build in front of you. When it doesn't, read the build files and work toward the goal by other means.

Read a Gradle build's repositories

The init script at https://docs.soh.gg/artifex/artifex-repositories.gradle prints every repository that a Gradle build uses as JSON without changing the build. In the build's root directory, enter the following commands:

curl -sO https://docs.soh.gg/artifex/artifex-repositories.gradle
./gradlew -q -I artifex-repositories.gradle artifexRepositories

The output lists the repositories in the settings file's pluginManagement and dependencyResolutionManagement blocks. It also lists each project's buildscript and dependency repositories in the order that Gradle requests them. Migrate the project dependency resolution context. When dependencyResolutionManagement declares repositories and projects add none, those declarations form that context.

Each repository entry includes its name, type, URL, whether credentials are set, and its content filters. The filters include releasesOnly and snapshotsOnly from mavenContent:

{
  "name": "Example releases",
  "type": "maven",
  "url": "https://maven.example.com/releases/",
  "credentials": { "username": "ruby", "password": "<set>" },
  "content": {
    "includes": [
      {
        "scope": "group",
        "match": "exact",
        "group": "com.example",
        "module": null,
        "version": null
      }
    ],
    "excludes": [],
    "includeConfigurations": [],
    "excludeConfigurations": []
  }
}

The scope and match JSON fields are wire names that an Artifex content rule takes. Don't confuse the scope field with Maven dependency scope.

Gradle exclusiveContent appears as include filters on the selected repository and matching exclude filters on every other repository. In Artifex, mark the selected upstream as the exclusive source instead. Passwords appear as <set> unless you run the build with -PartifexShowPasswords=true.

The script reports the filters as Gradle stores them. Gradle stores some filters as regular expressions even when the build wrote them as plain names. For example, includeModule("com.other", "widget") is stored and matched as a regular expression. When a regex pattern has no regular-expression characters other than ., an exact rule has the same effect and is clearer. If a repository's filters can't be read, the entry contains "content": "unreadable"; get its filters from the build files.

Repositories that a plugin adds when it is applied can appear in the output but not in the build files. This behavior is common with Minecraft, Android, and Spring plugins. To prevent Gradle from using those repositories after Artifex serves their contents, repositories { clear() } after the plugin is applied removes them all.

metadataSources { } is a per-repository setting that Artifex can't represent on an upstream. Record it in the report when a repository configures it.

Publication repositories are in the publishing { repositories { } } block of each project that applies maven-publish; the script doesn't list them.

Read a Maven build's repositories

Maven combines settings, active profiles, parent POMs, and the Super POM into its effective settings and effective POM. Generate both documents:

mvn -q help:effective-settings -Doutput=effective-settings.xml
mvn -q help:effective-pom -Doutput=effective-pom.xml

Read mirrors, servers, and the active profiles' repositories from the effective settings. Read repositories from the effective POM. A Maven mirror whose mirrorOf pattern covers a repository replaces that repository. Servers hold credentials by repository ID. distributionManagement in the effective POM names the publication repository.

Configure the build to use the repository

Gradle and Maven examples for resolving and publishing are on the repository's Overview page and in Resolve dependencies and Deploy artifacts. Use the build's Write token as the password, not your Manage token.

Verify the configuration

Compare the origin of every dependency before and after the change, not only the resolved version.

For Gradle, ./gradlew --refresh-dependencies --info dependencies logs the URL from which each file was downloaded. Capture the URLs before and after the change, and compare them. Gradle dependency lock files help only when the build already uses dependency locking.

For Maven, mvn -U -X dependency:resolve logs repository requests, and mvn dependency:tree -DoutputFile=tree.txt lets you compare versions. Start with an empty Gradle dependency cache or Maven local repository, or use --refresh-dependencies for Gradle and -U for Maven, so that dependency resolution checks the configured repositories instead of using cached artifacts.