detectAgent()

Scans the workspace root for well-known indicator files and returns the Jenkins agent label that matches the project's language. Eliminates the need for every team to hardcode agent { label '...' } in their Jenkinsfile.

---

Fallback chain

1. Dockerfile.ci check — if this file exists in the repo root, returns 'dockerfile' immediately. Takes priority over all indicator files. Used for multi-language projects that need a custom build environment.
2. Indicator file scan — checks the repo root for the files below, in order. Returns the label for the first match.
3. JENKINS_DEFAULT_AGENT env var — if no indicator file is found, checks whether this variable is set on the Jenkins controller and uses it. Lets operators define a platform-wide default without touching pipeline code.
4. Hard fail — if nothing matched, throws an error listing every supported indicator file so the developer knows exactly what to add.

---

Indicator file → agent label

File	Agent label
Dockerfile.ci	dockerfile ← highest priority
package.json	node-20
pom.xml	java-21
build.gradle / build.gradle.kts	java-21
go.mod	go-1.22
Cargo.toml	rust
requirements.txt	python-3.14
setup.py	python-3.14
pyproject.toml	python-3.14
Gemfile	ruby-3.3
composer.json	php

Labels match the agent templates defined in casc.yml. rust and php require a corresponding template to be added before use.

---

Dockerfile.ci — custom multi-language agent

Add a Dockerfile.ci to the repo root when the project needs more than one runtime in the same build stage. detectAgent() returns 'dockerfile' and standardPipeline() routes to a dockerfile { filename 'Dockerfile.ci' } agent block automatically.

# Example: Python backend and Node.js frontend in a single build environment
FROM python:3.14
RUN curl -fsSL https://deb.nodesource.com/setup_20.x | bash - \
    && apt-get install -y nodejs

---

Usage

// Load the shared library and let detectAgent pick the correct build environment
@Library('shared') _

pipeline {
    agent { label detectAgent() }
    stages {
        stage('Build') {
            steps {
                sh 'npm install'
            }
        }
    }
}

Note

agent { label detectAgent() } only works for label-based agents. For Dockerfile.ci projects, use standardPipeline() which handles the agent routing automatically.

---

Platform-wide default

Set JENKINS_DEFAULT_AGENT as a global environment variable in casc.yml to provide a fallback for repos that don't match any indicator file:

# Set a platform-wide default agent label used when no indicator file is found
jenkins:
  globalNodeProperties:
    - envVars:
        env:
          - key: JENKINS_DEFAULT_AGENT
            value: node-20