CloudBees Jenkins X Distribution to upstream Jenkins X migration guide

3 minute read

This migration guide provides instructions on how to migrate your entire CloudBees Jenkins X Distribution installation over to the Jenkins X upstream Open Source project.

Install upstream Jenkins X binary

Download and install the Jenkins X command-line binary archive for your workstation:

# Download the `.tar` file, unarchive it.
curl -L "$(curl --silent | jq -r '.tag_name')/jx-darwin-amd64.tar.gz" | tar xzv "jx"

# Add `jx` to your path
sudo mv jx /usr/local/bin

# verify installation
jx version --short
# Download the `.tar` file, and unarchive it in a directory where you can run the `jx` command.
curl -L "$(curl --silent "" | sed 's#.*tag/\(.*\)\".*#\1#')/jx-linux-amd64.tar.gz" | tar xzv "jx"

# Move binary to your path
sudo mv jx /usr/local/bin

# verify installation
jx version --short
  1. To install using Chocolatey package managerRight-click menu:Start\[Command Prompt (Admin)\].

  2. At the shell prompt, execute a powershell.exe command to download and install the choco binary and set the installation path so that the binary can be executed:

    @"%SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe" -NoProfile -InputFormat None -ExecutionPolicy Bypass -Command "iex ((New-Object System.Net.WebClient).DownloadString(''))" && SET "PATH=%PATH%;%ALLUSERSPROFILE%\chocolatey\bin"
  3. Install Jenkins X using Chocolatey:

    choco install jenkins-x

Find your Development environment

You can find the URL for your remote development (-dev) environment component by running the following command:

jx get environments

The output should be similar to the following:

NAME       LABEL       KIND        PROMOTE NAMESPACE     ORDER CLUSTER SOURCE                                                        REF PR
dev        Development Development Auto   jx-dev           0
staging    Staging     Permanent   Auto    jx-staging    100 
production Production  Permanent   Manual  jx-production 200 

The remote development environment (environment-acmedevenv-dev in the example) can be modified in your local clone copy on your workstation (usually a directory named cloudbees-jenkins-x-boot-config).

Next, remove the env/jx-app-ui directory:

rm -rf env/jx-app-ui/
rm -rf env/jx-app-ui/
rmdir /q /s env/jx-app-ui/

Remove the lines referencing the CloudBees Jenkins X Distribution UI jx-app-ui from env/requirements.yaml. It should look like the following:

- name: jx-app-ui
  version: 0.1.211

Configure upstream Jenkins X boot configuration

In your local cloudbees-jenkins-x-boot-config directory, edit the jx-requirements.yml file to support upstream Jenkins X boot configuration repository URL. The bootConfigURL setting by default is:


Change the URL to:


Remove Vault from pipeline

Remove the jx step boot vault pipeline step from the local -dev environment.

Edit the jenkins-x.yml file and remove the following step:

    - args:
    - step
    - boot
    - vault
    - --provider-values-dir
    - ../../kubeProviders
    command: jx
    dir: /workspace/source/systems/vault
    name: install-vault

Change CloudBees Jenkins X Distribution version stream to upstream Jenkins X

Switch the version stream from the CJXD to the upstream Jenkins X by editing the jx-requirements.yml file and looking for something lines similar to the following:

  ref: v0.0.36

Change these lines to the following (assuming ref: v1.0.535 is the most recent Jenkins X versionStream):

  ref: v1.0.535

Finalizing your migration

All the files removed and edited in all of the steps in this guide can be found in this example -dev commit:

Once the changes are committed and merged into your -dev environment mainline branch, follow the boot pipeline with the following:

 jx get build logs

Once the boot pipeline has finished successfully you can upgrade to the very latest release in your cluster:

jx upgrade boot

Review the changes in the generated pull request and if acceptable, type /approve in the PR Comment text box on GitHub site, then follow the boot pipeline logs to successful completion of your migration to upstream Jenkins X.

If you run into problems, need any help or guidance please ask in the the Jenkins X community