How to Configure JDK 25 for GitHub Copilot Coding Agent

GitHub Copilot coding agent runs in an ephemeral GitHub Actions environment where it can build your code, run tests, and execute tools. By default, it uses the pre-installed Java version on the runner—but what if your project needs a specific version like JDK 25?

In this post, I'll show you how to configure Copilot coding agent's environment to use any Java version, including the latest JDK 25, ensuring that Copilot can successfully build and test your Java projects.

The Problem

When Copilot coding agent works on your repository, it attempts to discover and install dependencies through trial and error. For Java projects, this means:

1. Copilot might try to use an older JDK version pre-installed on the runner


2. Build failures occur if your project requires newer Java features (records, pattern matching, virtual threads, etc.)


3. Time is wasted as Copilot tries different approaches to fix JDK-related issues

The solution? Preconfigure Copilot's environment with the exact JDK version your project needs.

The Solution: copilot-setup-steps.yml

GitHub provides a special workflow file called copilot-setup-steps.yml that runs before Copilot starts working. Think of it as your project's "pre-flight checklist" for Copilot.

Create this file at .github/workflows/copilot-setup-steps.yml:

name: "Copilot Setup Steps"



on:

  workflow_dispatch:

  push:

    paths:

      - .github/workflows/copilot-setup-steps.yml

  pull_request:

    paths:

      - .github/workflows/copilot-setup-steps.yml



jobs:

  # This job name MUST be exactly "copilot-setup-steps"

  copilot-setup-steps:

    runs-on: ubuntu-latest



    permissions:

      contents: read



    steps:

      - name: Checkout code

        uses: actions/checkout@v5



      - name: Set up JDK 25

        uses: actions/setup-java@v4

        with:

          java-version: '25'

          distribution: 'temurin'

          cache: 'maven'



      - name: Verify Java version

        run: java -version



      - name: Download dependencies

        run: mvn dependency:go-offline -B

Let's break down the key parts:

1. The Job Name is Critical

jobs:

  copilot-setup-steps:  # MUST be this exact name

Copilot only recognizes the job if it's named copilot-setup-steps. Any other name will be ignored.

2. Setting Up JDK 25 with setup-java

- name: Set up JDK 25

  uses: actions/setup-java@v4

  with:

    java-version: '25'

    distribution: 'temurin'

    cache: 'maven'

The actions/setup-java action supports multiple JDK distributions:

3. Caching Dependencies

cache: 'maven'

This caches your Maven dependencies between Copilot sessions, significantly speeding up subsequent runs. For Gradle projects, use cache: 'gradle'.

4. Pre-downloading Dependencies

- name: Download dependencies

  run: mvn dependency:go-offline -B

This ensures all dependencies are downloaded before Copilot starts. This is especially important if:

• You have private dependencies that require authentication


• Your project has many dependencies


• You want faster Copilot response times

Complete Example for a Maven Project

Here's a production-ready configuration for a Java 25 Maven project:

name: "Copilot Setup Steps"



on:

  workflow_dispatch:

  push:

    paths:

      - .github/workflows/copilot-setup-steps.yml

  pull_request:

    paths:

      - .github/workflows/copilot-setup-steps.yml



jobs:

  copilot-setup-steps:

    runs-on: ubuntu-latest



    permissions:

      contents: read



    steps:

      - name: Checkout code

        uses: actions/checkout@v5



      - name: Set up JDK 25

        uses: actions/setup-java@v4

        with:

          java-version: '25'

          distribution: 'temurin'

          cache: 'maven'



      - name: Verify Java version

        run: |

          java -version

          echo "JAVA_HOME=$JAVA_HOME"



      - name: Build and cache dependencies

        run: |

          mvn dependency:go-offline -B

          mvn compile -DskipTests -B

Gradle Configuration

For Gradle projects, adjust the workflow accordingly:

name: "Copilot Setup Steps"



on:

  workflow_dispatch:

  push:

    paths:

      - .github/workflows/copilot-setup-steps.yml

  pull_request:

    paths:

      - .github/workflows/copilot-setup-steps.yml



jobs:

  copilot-setup-steps:

    runs-on: ubuntu-latest



    permissions:

      contents: read



    steps:

      - name: Checkout code

        uses: actions/checkout@v5



      - name: Set up JDK 25

        uses: actions/setup-java@v4

        with:

          java-version: '25'

          distribution: 'temurin'

          cache: 'gradle'



      - name: Setup Gradle

        uses: gradle/actions/setup-gradle@v4



      - name: Build and cache dependencies

        run: ./gradlew dependencies --write-locks

Handling Private Dependencies

If your project uses private Maven repositories, you'll need to configure authentication. Create secrets in the copilot environment:

1. Go to your repository Settings → Environments
   


2. Click the copilot environment (create it if it doesn't exist)


3. Add environment secrets for your credentials

Then reference them in your workflow:

jobs:

  copilot-setup-steps:

    runs-on: ubuntu-latest



    permissions:

      contents: read



    steps:

      - name: Checkout code

        uses: actions/checkout@v5



      - name: Set up JDK 25

        uses: actions/setup-java@v4

        with:

          java-version: '25'

          distribution: 'temurin'

          cache: 'maven'

          server-id: private-repo

          server-username: ${{ secrets.MAVEN_USERNAME }}

          server-password: ${{ secrets.MAVEN_PASSWORD }}



      - name: Download dependencies

        run: mvn dependency:go-offline -B

Testing Your Configuration

The copilot-setup-steps.yml workflow automatically runs when you:

1. Push changes to the workflow file


2. Create a PR that modifies it


3. Manually trigger it from the Actions tab

This lets you validate your setup before Copilot uses it.

Tips for Java Projects

Compile the Code

Pre-compiling your code helps Copilot understand your codebase faster:

- name: Compile project

  run: mvn compile test-compile -DskipTests -B

Generate Sources

If you use code generation (Lombok processors, annotation processors, etc.):

- name: Generate sources

  run: mvn generate-sources generate-test-sources -B

Install the Project Locally

For multi-module Maven projects:

- name: Install modules

  run: mvn install -DskipTests -B

Using Larger Runners

For large Java projects, consider using larger GitHub-hosted runners:

jobs:

  copilot-setup-steps:

    runs-on: ubuntu-4-core  # More CPU and RAM

    # ... rest of configuration

Larger runners provide more resources for:

• Faster dependency downloads


• Quicker compilation


• Running memory-intensive tests

Conclusion

By creating a copilot-setup-steps.yml workflow, you ensure that GitHub Copilot coding agent has access to the exact Java version your project needs. This eliminates build failures, speeds up Copilot's work, and provides a consistent development environment.

Key takeaways:

1. 
   Create .github/workflows/copilot-setup-steps.yml with the exact job name copilot-setup-steps
   


2. 
   Use actions/setup-java@v4 to install JDK 25 or any version you need


3. 
   Enable caching for Maven or Gradle dependencies


4. 
   Pre-download dependencies to speed up Copilot's work


5. 
   Test your workflow by pushing changes or manually triggering it

Now Copilot can work with your Java 25 project just as effectively as it would on your local machine!

References:

• Customizing the development environment for GitHub Copilot coding agent


• actions/setup-java


• Supported Java distributions

Published: February 5, 2026