Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 43 additions & 0 deletions .github/copilot-instructions.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
# Copilot instructions

## Build, test, and lint

Use Node.js 24 or later (`package.json` declares `>=24.0.0`).

- `npm ci` installs the locked dependencies.
- `npm test` runs Jest serially with coverage.
- `npm test -- --runTestsByPath __tests__/setup-java.test.ts` runs one test file.
- `npm test -- --runTestsByPath __tests__/setup-java.test.ts --testNamePattern="pattern"` filters that file to matching test names.
- `npm run lint` runs ESLint on TypeScript files.
- `npm run format-check` checks Prettier formatting; `npm run format` applies it.
- `npm run build` bundles the setup and post-job entrypoints into `dist/`.
- `npm run check` runs format check, lint, build, and the full test suite.

## Architecture

This repository implements a Node.js GitHub Action. `action.yml` defines its inputs and outputs and runs `dist/setup/index.js` as the main entrypoint and `dist/cleanup/index.js` as the post-job entrypoint. The TypeScript sources in `src/` are bundled with NCC; the committed `dist/` files are what the action executes.

The setup entrypoint parses inputs, resolves versions, and configures the action's shared features. `src/distributions/distribution-factory.ts` lazily selects a vendor installer. Vendor installers implement metadata lookup and archive handling on top of `JavaBase` in `src/distributions/base-installer.ts`, which centralizes version resolution, tool-cache/JDK-cache use, download verification, and Java environment setup. Package support and OS/architecture support are validated centrally in `package-types.ts` and `platform-types.ts`.

The setup flow also configures problem matchers, Maven authentication and arguments, and Maven toolchains. The post-job entrypoint removes any isolated GPG home and saves enabled caches when the job succeeds and cache saving is not read-only.

## Repository-specific conventions

- Keep TypeScript source imports ESM-compatible: relative imports include the `.js` extension, even when the source file is `.ts`.
- Distribution-specific download and metadata logic belongs in its installer under `src/distributions/`; reuse `JavaBase` rather than duplicating common resolution, caching, verification, or environment behavior.
- When adding or changing distribution support, keep the distribution enum, factory, package-capability map, platform-capability map, README support documentation, unit tests, and relevant end-to-end workflow coverage consistent.
- Unit tests live under `__tests__/` and use Jest/ts-jest. Distribution tests are grouped under `__tests__/distributors/`; use the corresponding test and fixture patterns when changing an installer. End-to-end coverage is defined in `.github/workflows/e2e-*.yml`.
- Rebuild and commit generated `dist/` bundles for runtime-affecting source or dependency changes; do not make the bundles the source of truth. `npm run check` includes the build.
- New npm dependencies need lockfile changes and corresponding license records under `.licenses/`, following `.licensed.yml` and the licensed workflow.

## Action behavior principles

- Treat `action.yml` inputs, outputs, defaults, and compatibility aliases as the public API. Keep implementation, README, and advanced-usage documentation aligned when behavior changes; preserve deprecated aliases unless a documented breaking change removes them.
- Do not assume version syntax, package variants, or platform/architecture support is uniform across distributions. Keep capability checks and vendor resolution behavior consistent with the documented support matrix. `latest` means the newest stable GA release, not an early-access build.
- Preserve selection semantics: a recognized vendor in a supported version file may supply the distribution; otherwise the caller must provide it. If both `java-version` and `java-version-file` are given, the explicit `java-version` takes precedence.
- Preserve install-state behavior for multiple JDKs. The last installed JDK becomes the default unless `set-default: false`; all installed JDKs remain available through their version-specific environment variables and Maven toolchains. Toolchain entries accumulate non-destructively, and custom IDs must correspond one-for-one with requested versions.
- Treat dependency, wrapper, and JDK caches as distinct features with distinct keys and save behavior. `cache` enables dependency caching and implicitly enables JDK caching unless `cache-jdk` overrides it; `cache-read-only` restores without saving. Keep changes to cache identity or lifecycle aligned with these documented contracts.
- Preserve download-integrity guarantees: verify authoritative checksums when published. Signature verification is distribution-specific; explicit `verify-signature: true` must enforce verification where supported and fail clearly where unsupported. Do not silently weaken verification or imply that a cached install was downloaded and reverified.
- Keep Maven credential inputs as environment-variable names, not secret values. Generated settings and custom repository behavior must respect the documented overwrite option, while toolchain merging remains non-destructive and independent of that option.

See `docs/CONTRIBUTING.md` for contribution and validation guidance, `README.md` for the public contract, and `docs/advanced-usage.md` for detailed behavior and examples.
88 changes: 88 additions & 0 deletions .github/workflows/e2e-publishing.yml
Original file line number Diff line number Diff line change
Expand Up @@ -175,6 +175,94 @@ jobs:
throw "settings.xml file is not found in expected location"
}

test-maven-mirrors:
name: Maven mirrors (${{ matrix.mirror-of }})
runs-on: ${{ matrix.os }}
strategy:
fail-fast: false
matrix:
os: [macos-latest, windows-latest, ubuntu-latest]
mirror-of: ['*', 'external:*']
steps:
- name: Checkout
uses: actions/checkout@v7
with:
persist-credentials: false
- name: Configure Maven mirrors without repository inputs
uses: $/
with:
distribution: 'temurin'
java-version: '21'
settings-path: ${{ runner.temp }}/maven-mirror-test
mvn-server-credentials: |
private:PRIVATE_USERNAME:PRIVATE_TOKEN
mvn-mirrors: |
private:https://mirror.example.invalid/maven:${{ matrix.mirror-of }}
- name: Validate generated settings and Maven mirror selection
env:
MIRROR_OF: ${{ matrix.mirror-of }}
PRIVATE_USERNAME: mirror-test-user
PRIVATE_TOKEN: mirror-test-token
run: |
$directory = Join-Path $env:RUNNER_TEMP "maven-mirror-test"
$settingsPath = Join-Path $directory "settings.xml"
[xml]$settings = Get-Content -Path $settingsPath -Raw
$mirrors = @($settings.settings.mirrors.mirror)
if ($mirrors.Count -ne 1 -or $mirrors[0].id -ne "private" -or $mirrors[0].url -ne "https://mirror.example.invalid/maven" -or $mirrors[0].mirrorOf -ne $env:MIRROR_OF) {
throw "Incorrect generated mirror"
}
if ($settings.settings.profiles -or $settings.settings.activeProfiles) {
throw "Mirror-only settings must not add repository profiles"
}
$server = $settings.settings.servers.server
if ($server.id -ne "private" -or $server.username -ne '${env.PRIVATE_USERNAME}' -or $server.password -ne '${env.PRIVATE_TOKEN}') {
throw "Mirror credentials were not preserved"
}

$pomPath = Join-Path $directory "pom.xml"
@'
<project xmlns="http://maven.apache.org/POM/4.0.0">
<modelVersion>4.0.0</modelVersion>
<groupId>setup-java.test</groupId>
<artifactId>mirror-settings</artifactId>
<version>1.0</version>
<repositories>
<repository>
<id>pom-dependencies</id>
<url>https://dependencies.example.invalid/maven</url>
</repository>
</repositories>
<pluginRepositories>
<pluginRepository>
<id>pom-plugins</id>
<url>https://plugins.example.invalid/maven</url>
</pluginRepository>
</pluginRepositories>
</project>
'@ | Set-Content -Path $pomPath

# validate requires no plugins or dependencies, so mirror selection can
# be inspected offline without contacting the deliberately invalid URLs.
$output = & mvn --batch-mode --no-transfer-progress --offline --debug `
--settings $settingsPath --file $pomPath `
"-Dmaven.repo.local=$directory/repository" validate 2>&1
if ($LASTEXITCODE -ne 0) {
throw "Could not inspect Maven mirror selection: $output"
}
$log = $output -join "`n"
foreach ($id in @("central", "pom-dependencies")) {
$expected = "Using mirror private (https://mirror.example.invalid/maven) for $id ("
if (-not $log.Contains($expected)) {
throw "Maven did not select the mirror for ${id}: $log"
}
}
foreach ($type in @("dependencies", "plugins")) {
$pattern = 'Repositories \(' + $type + '\)\s*: \[private \(https://mirror\.example\.invalid/maven, [^\]]+\)\]'
if ($log -notmatch $pattern) {
throw "Maven did not redirect all $type repositories: $log"
}
}

test-maven-repositories:
name: Maven ${{ matrix.repositories }} repositories
runs-on: ${{ matrix.os }}
Expand Down
2 changes: 1 addition & 1 deletion .licenses/npm/@actions/cache.dep.yml

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion .licenses/npm/@azure/core-client.dep.yml

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

32 changes: 32 additions & 0 deletions .licenses/npm/@azure/core-rest-pipeline-1.23.0.dep.yml

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

4 changes: 2 additions & 2 deletions .licenses/npm/@azure/storage-blob.dep.yml

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion .licenses/npm/@azure/storage-common.dep.yml

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion .licenses/npm/@nodable/entities.dep.yml

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion .licenses/npm/@typespec/ts-http-runtime.dep.yml

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion .licenses/npm/fast-xml-parser.dep.yml

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion .licenses/npm/undici.dep.yml

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

6 changes: 6 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -171,6 +171,7 @@ steps:
| `mvn-server-repository-origins` | Multiline Maven credential origins in the format `server-id:repository-origin`. Each origin must belong to a configured server ID. Requires Maven 3.10+. | |
| `mvn-repositories` | Multiline Maven dependency repositories in the format `repository-id:repository-url:snapshots-enabled`. | |
| `mvn-plugin-repositories` | Multiline Maven plugin repositories in the format `repository-id:repository-url:snapshots-enabled`. Can be used independently of `mvn-repositories`. | |
| `mvn-mirrors` | Multiline Maven mirrors in the format `mirror-id:mirror-url:mirror-of`. Redirect matching dependency and plugin repositories; use a matching server ID for authentication. | |
| `mvn-repositories-include-central` | Include Maven Central for dependency and plugin repositories in the generated profile. When `false`, Central is disabled for both types unless that type explicitly declares `central`. Has no effect when neither repository list is configured. | `true` |
| `mvn-repositories-prioritize-central` | Place Maven Central before custom dependency and plugin repositories. Has no effect when Central is excluded or neither repository list is configured. | `true` |
| `settings-path` | Directory where `settings.xml` is written. | `~/.m2` |
Expand Down Expand Up @@ -490,6 +491,11 @@ match `mvn-server-credentials` IDs when authentication is required.
See [Resolving Maven dependencies from custom repositories](docs/advanced-usage.md#resolving-maven-dependencies-from-custom-repositories)
and [Resolving Maven plugins from custom repositories](docs/advanced-usage.md#resolving-maven-plugins-from-custom-repositories).

To redirect repositories, including Central and repositories declared in project
or parent POMs, use [`mvn-mirrors`](docs/advanced-usage.md#redirecting-maven-repositories-with-mirrors).
It works independently of the repository inputs; a `mirrorOf` pattern of `*`
routes all dependency and plugin repositories through the configured mirror.

> [!WARNING]
> `mvn-repositories-include-central: false` now disables inherited Maven Central
> for **both dependencies and plugins**, even in existing workflows that only
Expand Down
Loading
Loading