IntelliJ Run/Debug Configuration Portability Between Developer Workstations and CI Agents

Direct answer

Commit only individual run-configuration files under .idea/runConfigurations/, and only after removing absolute paths and hard-coded JDK locations. Do not commit .idea/workspace.xml; it stores machine-specific absolute paths, local environment values, and window layout. Use IDE path macros such as $PROJECT_DIR$ or $MODULE_DIR$ for working directories and file references, and set the SDK to “Use project SDK” or a shared variable such as $JDK_HOME$ that CI resolves through JAVA_HOME.

Likely explanation

A configuration that works on a workstation usually embeds absolute paths to the developer’s checkout, local environment variables, and an absolute JDK home. When the same XML is copied to a headless agent, those directories do not exist, variables are undefined, and the referenced JDK may be missing or a different major version. The result is a silent failure, a “directory not found” error, or a class-version mismatch.

Confirmed facts

• .idea/workspace.xml is per-user and non-portable; add it to .gitignore.
• Run configurations saved as separate XML files under .idea/runConfigurations/ are the subset meant for sharing.
• Path macros resolve relative to the project root, so the same XML works on any machine that checks out the repository to a comparable root.
• The JDK is portable when the configuration references a project SDK or an environment variable rather than a hard-coded path such as /Library/Java/JavaVirtualMachines/....

Assumes IntelliJ IDEA 2023.x or later with a Git repository. Older editions may store run configurations differently; inspect your .idea directory before generalizing.

Steps for this case

1. Open the working Run/Debug configuration in IntelliJ.
2. Change every absolute path to $PROJECT_DIR$ or $MODULE_DIR$.
3. Set the SDK to “Use project SDK” or define JAVA_HOME on both workstation and CI; do not store an absolute JDK path.
4. Set the working directory to $PROJECT_DIR$.
5. Save the configuration, which writes .idea/runConfigurations/<name>.xml.
6. Inspect the XML for absolute paths, then commit only that file.
7. Add .idea/workspace.xml to .gitignore if it is not already ignored.

Enforcing JDK and working-directory parity

On CI, export JAVA_HOME to the same JDK major version used by developers, then run java -version as a pipeline step. Because the configuration uses $PROJECT_DIR$, the agent resolves the working directory to the checked-out repository root automatically. Document the required JDK version and variable name in the repository README so workstations and agents converge without duplicating the run configuration.

Verification

git check-ignore .idea/workspace.xml
grep -R -E "/Users|/home|C:" .idea/runConfigurations/ || echo "no absolute paths found"
echo "$JAVA_HOME"
java -version

If git check-ignore returns exit code 0, workspace.xml is ignored. If grep finds matches, remove those absolute paths before committing.

Missing diagnostic detail

Does your CI agent execute the IntelliJ run-configuration XML directly, or does it invoke Maven, Gradle, or npm scripts? If CI uses build scripts, the committed XML should document the intended command, but the pipeline should call the build tool directly rather than launching the IDE configuration.