Introduction to Jenkins Converter

today • 2 min read

The CircleCI Jenkins Converter is a web tool that allows you to easily convert a Jenkinsfile to a CircleCI config.yml, helping you to get started building on CircleCI quickly and easily.

Currently, the converter only supports declarative Jenkinsfiles. While the number of supported plug-ins and steps continue to be expanded, the hope is that this tool gets you started at least 50% of the way, and makes it easier for you to get started building on CircleCI.

Limitations

A limited number of syntaxes and plugins are supported. Jenkinsfiles relying on unsupported syntaxes and plugins cannot be converted. Please manually remove them.
Only a single Jenkinsfile is accepted per request. Namely, Shared Libraries will not be resolved, and the resulting config.yml may be incomplete. Note that under certain cases the converter does not raise errors even if there are unresolvable Shared Libraries.
Only Default is supported as a tool name for maven, jdk and gradle in the tools block, and other names will cause conversion failures. Please configure them as follows or remove them manually.

For example, the following stanza:
```
tools {
  maven 'Maven 3.6.3'
  jdk 'Corretto 8.232'
}
```
should be changed to:
```
tools {
  maven 'Default'
  jdk 'Default'
}
```

Next steps after conversion

Executors

A static Docker executor, cimg/base, is inserted as the executor regardless of the one defined within the Jenkinsfile input.

Given that cimg/base is a very lean image, it’s highly likely that your project will require a different image. CircleCI’s convenience images are a good place to find other images. Refer to custom Docker image for advanced steps to create your own custom image.

Depending on the use case, you might require the machine executor if your application requires full access to OS resources and the job environment, or the macOS executor.

Workflows

CircleCI Workflows (the equivalent of Jenkins pipelines) are transferred from your Jenkinsfile to the config.yml, including branch filters. The converter will not transfer any scheduled builds to prevent unintentional builds from being triggered.

Jobs

Many of the configuration options within CircleCI jobs don’t have equivalents to Jenkins’ offerings. It is best practice to start with the following features to get a richer experience from CircleCI:

Steps

While the Jenkinsfile Converter attempts to directly translate steps, it does not provide full translation of all steps. To address this, the JFC_STACK_TRACE key was added to translate specific steps within the output YAML and to provide some guidance on how to proceed with unsupported step directives.

Supported syntax

Only declarative (pipeline) Jenkinsfiles are currently supported.

Jenkinsfile Syntax	Approx. CircleCI Syntax	Status
agent	executor	Static
post	when attribute	See when
stages	workflows	Supported
steps	step	Limited
environment	environment	Unsupported
options	N/A	See Supported Jenkins Plugins
parameters	parameters	Unsupported
triggers	cron	Unsupported
stage	job	Supported

Supported Jenkins plugins

Note: Jenkinsfiles relying on plugins not listed below cannot be converted. Please remove stanzas relying on those unsupported plugins (for example options), otherwise you will see an error message saying something is “Unknown” or “Invalid”. Please submit a ticket with our support center if you have a request to add a plugin to the list.

Trilead API Plugin (trilead-api)
Folders Plugin (cloudbees-folder)
OWASP Markup Formatter Plugin (antisamy-markup-formatter)
Script Security Plugin (script-security)
Oracle Java SE Development Kit Installer Plugin (jdk-tool)
Command Agent Launcher Plugin (command-launcher)
Structs Plugin (structs)
Pipeline: Step API (workflow-step-api)
Token Macro Plugin (token-macro)
bouncycastle API Plugin (bouncycastle-api)
Build Timeout (build-timeout)
Credentials Plugin (credentials)
Plain Credentials Plugin (plain-credentials)
SSH Credentials Plugin (ssh-credentials)
Credentials Binding Plugin (credentials-binding)
SCM API Plugin (scm-api)
Pipeline: API (workflow-api)
Timestamper (timestamper)
Pipeline: Supporting APIs (workflow-support)
Durable Task Plugin (durable-task)
Pipeline: Nodes and Processes (workflow-durable-task-step)
JUnit Plugin (junit)
Matrix Project Plugin (matrix-project)
Resource Disposer Plugin (resource-disposer)
Jenkins Workspace Cleanup Plugin (ws-cleanup)
Ant Plugin (ant)
JavaScript GUI Lib: ACE Editor bundle plugin (ace-editor)
JavaScript GUI Lib: jQuery bundles (jQuery and jQuery UI) plugin (jquery-detached)
Pipeline: SCM Step (workflow-scm-step)
Pipeline: Groovy (workflow-cps)
Pipeline: Job (workflow-job)
Jenkins Apache HttpComponents Client 4.x API Plugin (apache-httpcomponents-client-4-api)
Display URL API (display-url-api)
Jenkins Mailer Plugin (mailer)
Pipeline: Basic Steps (workflow-basic-steps)
Gradle Plugin (gradle)
Pipeline: Milestone Step (pipeline-milestone-step)
Jackson 2 API Plugin (jackson2-api)
Pipeline: Input Step (pipeline-input-step)
Pipeline: Stage Step (pipeline-stage-step)
Pipeline Graph Analysis Plugin (pipeline-graph-analysis)
Pipeline: REST API Plugin (pipeline-rest-api)
JavaScript GUI Lib: Handlebars bundle plugin (handlebars)
JavaScript GUI Lib: Moment.js bundle plugin (momentjs)
Pipeline: Stage View Plugin (pipeline-stage-view)
Pipeline: Build Step (pipeline-build-step)
Pipeline: Model API (pipeline-model-api)
Pipeline: Declarative Extension Points API (pipeline-model-extensions)
Jenkins JSch dependency plugin (jsch)
Jenkins Git client plugin (git-client)
Jenkins GIT server Plugin (git-server)
Pipeline: Shared Groovy Libraries (workflow-cps-global-lib)
Branch API Plugin (branch-api)
Pipeline: Multibranch (workflow-multibranch)
Authentication Tokens API Plugin (authentication-tokens)
Docker Commons Plugin (docker-commons)
Docker Pipeline (docker-workflow)
Pipeline: Stage Tags Metadata (pipeline-stage-tags-metadata)
Pipeline: Declarative Agent API (pipeline-model-declarative-agent)
Pipeline: Declarative (pipeline-model-definition)
Lockable Resources plugin (lockable-resources)
Pipeline (workflow-aggregator)
GitHub API Plugin (github-api)
Jenkins Git plugin (git)
GitHub plugin (github)
GitHub Branch Source Plugin (github-branch-source)
Pipeline: GitHub Groovy Libraries (pipeline-github-lib)
MapDB API Plugin (mapdb-api)
Jenkins Subversion Plug-in (subversion)
SSH Build Agents plugin (ssh-slaves)
Matrix Authorization Strategy Plugin (matrix-auth)
PAM Authentication plugin (pam-auth)
LDAP Plugin (ldap)
Email Extension Plugin (email-ext)
H2 API Plugin (h2-api)
Config File Provider Plugin (config-file-provider)
Pipeline Maven Integration Plugin (pipeline-maven)
Pipeline Utility Steps (pipeline-utility-steps)

Feedback

To share any general feedback regarding this project, submit a ticket with our CircleCI Support team.

Help make this document better

This guide, as well as the rest of our docs, are open source and available on GitHub. We welcome your contributions.

Suggest an edit to this page (please read the contributing guide first).
To report a problem in the documentation, or to submit feedback and comments, please open an issue on GitHub.
CircleCI is always seeking ways to improve your experience with our platform. If you would like to share feedback, please join our research community.

Need support?

Our support engineers are available to help with service issues, billing, or account related questions, and can help troubleshoot build configurations. Contact our support engineers by opening a ticket.

You can also visit our support site to find support articles, community forums, and training resources.

CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.