diff --git a/.github/workflows/java-sdk-tests.yml b/.github/workflows/java-sdk-tests.yml
index bd0a34bd25..918e6ce10f 100644
--- a/.github/workflows/java-sdk-tests.yml
+++ b/.github/workflows/java-sdk-tests.yml
@@ -40,10 +40,13 @@ jobs:
with:
node-version: 22
+ - name: Validate Linux glibc native host
+ run: node copilot-native/scripts/validate-native-host.mjs linux-x64
+
- name: Run Java SDK tests (InProcess)
env:
CI: "true"
- run: mvn clean verify -Pinprocess
+ run: mvn clean verify -Pinprocess -Dcopilot.native.skip.download=false
- name: Generate Test Report Summary
if: always()
@@ -125,7 +128,9 @@ jobs:
if: matrix.test-jdk == '25'
env:
CI: "true"
- run: mvn verify -Dskip.test.harness=true
+ run: |
+ node copilot-native/scripts/validate-native-host.mjs linux-x64
+ mvn verify -Dskip.test.harness=true -Dcopilot.native.libc=glibc -Dcopilot.native.skip.download=false
- name: Switch to JDK 17
if: matrix.test-jdk == '17'
diff --git a/java/README.md b/java/README.md
index 2f8ca3dfa3..6c6124e959 100644
--- a/java/README.md
+++ b/java/README.md
@@ -487,6 +487,45 @@ mvn verify -Dskip.test.harness=true
mvn jacoco:prepare-agent@wire-up-coverage-instrumentation antrun:run@print-test-jdk-banner surefire:test failsafe:integration-test failsafe:verify jacoco:report@build-coverage-report-from-tests -Denforcer.skip=true
```
+#### Development Setup for native embedding
+
+Run native-runtime Maven commands from the `java` directory. Native packaging requires Node.js and npm in addition to JDK 25 and Maven because `copilot-native/scripts/fetch-native.mjs` retrieves the pinned npm runtime package.
+
+Validated on a native Linux x64 glibc host: Maven activates the `native-linux-x64` profile on Linux `amd64` when `copilot.native.libc=glibc` is set. The build validates the host before downloading or packaging native files. The profile runs the native script tests, fetches the pinned `@github/copilot-linux-x64` package during `generate-resources`, packages the `linux-x64` classifier JAR during `package`, and verifies its native contents. An absent or explicitly false `copilot.native.skip.download` value preserves normal native packaging. Ensure npm can authenticate to the package registry before running the build.
+
+Before opting in, validate that Node.js reports glibc for the build host:
+
+```bash
+node copilot-native/scripts/validate-native-host.mjs linux-x64
+mvn -pl copilot-native clean verify -Dcopilot.native.libc=glibc
+```
+
+The `inprocess` test profile performs the same validation and native packaging automatically, so the full in-process test command remains:
+
+```bash
+mvn -Pinprocess clean verify
+```
+
+On macOS, Windows, Linux ARM64, Linux x64 musl, and other unsupported hosts, do not set `copilot.native.libc=glibc`. A normal build produces only the OS-neutral primary, sources, and Javadoc JARs; it does not run the Linux x64 native script tests, download or stage Linux native files, or produce a `linux-x64` classifier JAR.
+
+To build only the OS-neutral artifacts on any host, or override the glibc opt-in, disable native download and packaging:
+
+```bash
+mvn -pl copilot-native clean package -DskipTests -Dcopilot.native.libc=glibc -Dcopilot.native.skip.download=true
+```
+
+The verified Linux x64 checks are:
+
+```bash
+node --test copilot-native/scripts/fetch-native.test.mjs copilot-native/scripts/validate-native-host.test.mjs
+mvn -pl copilot-native help:active-profiles -Dcopilot.native.libc=glibc -Dcopilot.native.skip.download=false
+mvn -pl copilot-native test -Dcopilot.native.libc=glibc
+mvn clean verify -Dcopilot.native.libc=glibc
+mvn clean package -pl copilot-native -DskipTests -Dcopilot.native.libc=glibc -Dcopilot.native.skip.download=true
+```
+
+On a supported Linux x64 host, the classifier JAR contains `native/linux-x64/runtime.node`, `native/linux-x64/platform.properties`, and `native/linux-x64/copilot`. The placeholder JAR remains OS-neutral and contains no native binaries. Unsupported hosts retain the placeholder-only behavior without producing a `-linux-x64.jar`.
+
## License
MIT — see [LICENSE](sdk/LICENSE) for details.
diff --git a/java/copilot-native/pom.xml b/java/copilot-native/pom.xml
index 642f9171a4..775fad47da 100644
--- a/java/copilot-native/pom.xml
+++ b/java/copilot-native/pom.xml
@@ -17,7 +17,7 @@
jar
GitHub Copilot SDK :: Java :: Native Runtime
- Native runtime binaries for the GitHub Copilot Java SDK, published as per-platform classifier JARs
+ Native runtime artifacts for the GitHub Copilot Java SDK, with host-matched platform classifier JARs
https://github.com/github/copilot-sdk
@@ -35,12 +35,6 @@
its SHA-512 integrity hash.
-->
${project.basedir}/../..
-
- linux-x64
${project.build.directory}/native-staging
org.codehaus.mojo
exec-maven-plugin
- fetch-native-linux-x64
- generate-resources
+ validate-native-host
+ none
+
+ exec
+
+
+ node
+
+ ${project.basedir}/scripts/validate-native-host.mjs
+ ${copilot.native.classifier}
+
+
+
+
+ fetch-native
+ none
exec
@@ -93,15 +102,17 @@
test-fetch-native
- test
+ none
exec
+ ${skipTests}
node
--test
${project.basedir}/scripts/fetch-native.test.mjs
+ ${project.basedir}/scripts/validate-native-host.test.mjs
@@ -118,8 +129,8 @@
native//platform.properties.
-->
- jar-linux-x64
- package
+ jar-native
+ none
jar
@@ -173,7 +184,7 @@
verify-native-jars
- package
+ none
run
@@ -193,10 +204,10 @@
-
+
-
+
@@ -221,6 +232,124 @@
+
+
+ native-linux-x64
+
+
+ Linux
+ amd64
+
+
+ copilot.native.libc
+ glibc
+
+
+
+ linux-x64
+ copilot
+
+
+
+
+ org.codehaus.mojo
+ exec-maven-plugin
+
+
+ validate-native-host
+ validate
+
+
+ fetch-native
+ generate-resources
+
+
+ test-fetch-native
+ test
+
+
+
+
+ org.apache.maven.plugins
+ maven-jar-plugin
+
+
+ jar-native
+ package
+
+
+
+
+ org.apache.maven.plugins
+ maven-antrun-plugin
+
+
+ verify-native-jars
+ package
+
+
+
+
+
+
+
+
+ inprocess
+
+ linux-x64
+ copilot
+
+
+
+
+ org.codehaus.mojo
+ exec-maven-plugin
+
+
+ validate-native-host
+ validate
+
+
+ fetch-native
+ generate-resources
+
+
+ test-fetch-native
+ test
+
+
+
+
+ org.apache.maven.plugins
+ maven-jar-plugin
+
+
+ jar-native
+ package
+
+
+
+
+ org.apache.maven.plugins
+ maven-antrun-plugin
+
+
+ verify-native-jars
+ package
+
+
+
+
+
+