Warning

The product is in closed beta and not open to the public.

VisionByte SCM Plugin User Guide

Use the VisionByte SCM Plugin to check out source code, review build changes, and automatically build when selected branches change. It supports Freestyle, Scripted Pipeline, Declarative Pipeline, and Multibranch Pipeline.

This guide covers version 0.1.0.1. See the Release Notes for the release summary.

Requirements

  • Jenkins: 2.528.3 or later.

  • Java: A 64-bit runtime supported by your Jenkins version on the controller and agents. OpenJDK 21 is the recommended baseline.

  • Build nodes: Windows x64, Linux x86_64 with glibc or musl, or macOS on Apple Silicon (arm64). On macOS, use an ARM64 Java runtime; Intel/Rosetta JVMs are not supported.

  • Plugins: Jenkins Credentials and SCM API with their required dependencies. Pipeline jobs also need Jenkins Pipeline; Declarative scripts need Pipeline: Declarative. Install Pipeline: Multibranch for Multibranch jobs or scripts that use checkout scm.

  • Repository access: The build node must be able to access the repository over HTTP or HTTPS. Pipeline script from SCM and Multibranch jobs also require repository access from the controller, which must use a supported platform. Private repositories require an account with read and synchronization permissions.

A separate VisionByte command-line installation is not required on build nodes.

Installation

  1. Obtain the visionbyte-scm.hpi package.

  2. Open Manage Jenkins → Plugins and install the required plugins listed above if they are not already present.

  3. Under Advanced settings → Deploy Plugin, upload the HPI package.

  4. Restart Jenkins after active builds have finished, then confirm that VisionByte SCM Plugin is enabled.

  5. When upgrading, restart agent JVMs as well.

Credentials

For a private repository, open Manage Jenkins → Credentials and add a credential available to the job:

  • Kind: Username with password.

  • Scope: Global.

  • Username / Password: Your VisionByte account details.

  • ID: A recognizable name, such as vb-read.

For a Multibranch project, credentials stored in its parent folder can also be used. Select this credential in the job configuration or use its ID as credentialsId in Pipeline. Leave Credentials empty for anonymous access. Do not include a username or password in the repository URL.

Freestyle Quick Start

  1. Select New Item → Freestyle project and enter a job name.

  2. Assign the job to a supported build node.

  3. Under Source Code Management, select VisionByte and enter the repository URL and optional credentials. Under Branches to build, enter trunk or add other branch names or patterns.

  4. If needed, enable General → Advanced → Use custom workspace, for example D:/jenkins-workspaces/my-project.

  5. Add your build steps, save, and select Build Now.

  6. In Console Output, look for Checked out VisionByte revision: followed by the full UUID of the version used for this build.

The first checkout requires an empty workspace outside any existing VisionByte checkout, including checkouts in its parent directories. Use a separate workspace for each job. Disable concurrent builds when using a fixed custom workspace. When changing the repository URL, use a fresh workspace.

Repository Configuration

SCM settings

Field

Pipeline parameter

Description

Repository URL

repositoryUrl

HTTP/HTTPS repository address.

Credentials

credentialsId

Optional username/password credential ID.

Branches to build

branches

At least one branch entry. The initial UI entry is trunk; a blank entry means all open branches.

Revert local changes before checkout

revertBeforeCheckout

Discard local changes to tracked files. Default: false.

Clean untracked files before checkout

cleanBeforeCheckout

Remove untracked files. Default: false.

Branch Names and Patterns

Use Add branch to enter several targets. Each Freestyle or ordinary Pipeline build checks out one selected version. To select several targets in Pipeline:

branches: [[name: 'trunk'], [name: 'release/*']]

Names and patterns are case sensitive:

Branch selection examples

Entry

Selection

trunk

The branch named trunk.

release/*

Names such as release/1.0; * does not match /.

release/**

Includes nested names such as release/maintenance/1.0.

release/?

A single character after release/, such as release/1.

** or a blank entry

All open branches, including names containing /.

Patterns discover open branches, not tags. An ordinary job can also select a tag by its exact name or pin a version with a full UUID. New matching branches are picked up by later polls. If no branches match, polling does not start a build; a manual build reports an error.

With several targets, unbuilt candidate versions are selected oldest first. Identical versions are built once, and versions already included in another matching candidate are skipped. Freestyle queues another build when candidates remain; ordinary Pipeline jobs pick them up on later polls. Use Multibranch Pipeline when you want a separate job and build history for every branch.

When upgrading existing Pipeline snippets, replace revision: 'trunk' with branches: [[name: 'trunk']]. Review existing job configurations and keep at least one branch entry. The cleanup options are explained below.

Pipeline

Create a Pipeline job and choose Pipeline script. Use the standard checkout step with $class: 'VisionByteSCM'.

To generate a snippet, open Pipeline Syntax, select checkout: Check out from version control, choose VisionByte under SCM, fill in the settings, and select Generate Pipeline Script.

Declarative Pipeline

The following example uses a custom Windows workspace, enables polling, and passes the checked-out revision to a build command:

def vb = [:]

pipeline {
    agent {
        node {
            label 'windows'
            customWorkspace 'D:/jenkins-workspaces/my-project'
        }
    }
    options {
        skipDefaultCheckout()
        disableConcurrentBuilds()
    }
    triggers {
        pollSCM('H/5 * * * *')
    }
    stages {
        stage('Checkout') {
            steps {
                script {
                    vb = checkout(
                        changelog: true,
                        poll: true,
                        scm: [$class: 'VisionByteSCM',
                              repositoryUrl: 'https://vb.example.com/project',
                              credentialsId: 'vb-read',
                              branches: [[name: 'trunk']]])
                }
            }
        }
        stage('Build') {
            steps {
                script {
                    withEnv(["VB_REVISION=${vb.VB_REVISION}"]) {
                        bat 'echo Building revision %VB_REVISION%'
                    }
                }
            }
        }
    }
}

Replace the label, workspace, URL, and credential ID with your own values, and replace echo with your build commands. Omit credentialsId for anonymous access. On Linux, choose a suitable node and workspace path, and use sh 'echo "Building revision $VB_REVISION"' instead of bat.

Scripted Pipeline

Use the same checkout settings inside node and ws:

node('windows') {
    ws('D:/jenkins-workspaces/my-project-scripted') {
        def vb = checkout(
            changelog: true,
            poll: true,
            scm: [$class: 'VisionByteSCM',
                  repositoryUrl: 'https://vb.example.com/project',
                  credentialsId: 'vb-read',
                  branches: [[name: 'trunk']]])
        withEnv(["VB_REVISION=${vb.VB_REVISION}"]) {
            bat 'echo Building revision %VB_REVISION%'
        }
    }
}

For Scripted Pipeline, configure Poll SCM in the job if automatic builds are needed. Set poll: false to exclude the checkout from polling, or changelog: false to omit its change log.

Run the job manually once before relying on polling. After changing the repository or target in the script, run it manually again.

Pipeline Script from SCM

To store the Pipeline script in VisionByte:

  1. Commit a Jenkinsfile to the repository.

  2. In the Pipeline job, select Pipeline script from SCM and choose VisionByte as the SCM.

  3. Enter the repository URL, credentials, and Branches to build.

  4. Set Script Path to Jenkinsfile or a repository-relative path such as ci/Jenkinsfile.

  5. Clear Lightweight checkout, save, and run the job.

In the Jenkinsfile, use checkout scm to reuse the job’s repository and selected version. For example:

properties([disableConcurrentBuilds()])
node('windows') {
    ws('D:/jenkins-workspaces/my-project') {
        stage('Checkout and build') {
            def vb = checkout scm
            withEnv(["VB_REVISION=${vb.VB_REVISION}"]) {
                bat 'echo Building revision %VB_REVISION%'
            }
        }
    }
}

Declarative Pipeline can use its default checkout, or combine skipDefaultCheckout() with an explicit checkout scm. The build uses the same version that supplied its Jenkinsfile, even if the branch changes meanwhile.

Jenkins reads the script before applying workspace settings in the Jenkinsfile. Keep the controller’s Jenkins home and script workspace outside any existing VisionByte checkout. For a development server, use a Jenkins home outside the source tree. Lightweight checkout must remain disabled.

Multibranch Pipeline

Use Multibranch Pipeline to create a separate job for each matching branch that contains a Jenkinsfile:

  1. Install Pipeline: Multibranch, then create a Multibranch Pipeline item.

  2. Under Branch Sources, select Add source → VisionByte.

  3. Enter the repository URL and optional credentials.

  4. Configure Branches to discover. The default **, or a blank entry, discovers all open branches. Use names or patterns to limit discovery.

  5. Under Build Configuration, set Script Path to Jenkinsfile or a path such as ci/Jenkinsfile.

  6. Save and select Scan Multibranch Pipeline Now.

  7. To discover later changes automatically, enable Periodically if not otherwise run under the scan triggers and select an interval.

Use checkout scm or Declarative Pipeline’s default checkout in each branch’s Jenkinsfile. Jenkins supplies BRANCH_NAME; VisionByte checkout also provides the VB_* values described below. Use normal per-job workspaces rather than one fixed custom workspace shared by all branch jobs.

Repeated scans do not rebuild unchanged branch versions. New branches and changed versions follow the project’s build strategy. Closed branches and branches that no longer contain the script follow Orphaned Item Strategy. Configure this policy to control how long their jobs and build history remain.

Unlike an ordinary job with several branch entries, Multibranch keeps a job for each matching branch even when its version is already included in another branch. Tags and pull requests are not discovered.

SCM Polling and Automatic Builds

In a Freestyle job, enable Build Triggers → Poll SCM and enter a schedule. Pipeline can use the same trigger or the pollSCM directive shown above. For example:

H/5 * * * *

This checks approximately every five minutes and starts a build when a configured target has an unbuilt candidate version. The build node must be online. Open the job’s Polling Log to check polling results.

Only configured names and matching open branches are considered. A fixed full UUID does not trigger builds for later revisions. Polling does not change workspace files or run cleanup. For Multibranch projects, configure periodic branch scans as described above to discover new branches and changes.

Build Results and Variables

Use Console Output to follow download, rebuild, and checkout progress and view operation timings or errors. Open Changes to review revision summaries, authors, dates, descriptions, and changed files. Revision and file links open the corresponding VisionByte server pages; your browser may require a separate server login.

The first checkout and builds without new revisions have empty change logs. For jobs with several targets, changes and previous-version values belong to the selected target. Changing the repository or configured target list starts a new change-log baseline. Repeated checkouts of the same version in one build do not duplicate change-log entries.

Freestyle build steps receive these environment variables. Pipeline receives the same values from checkout; use withEnv to pass them to commands as shown in the examples.

Build variables

Variable

Description

VB_REVISION

Full UUID checked out for this build.

VB_TARGET_REVISION

Selected branch, exact tag, or UUID. A pattern reports the actual selected branch name, rather than the pattern.

VB_REPOSITORY_URL

Repository URL used for this build.

VB_PREVIOUS_REVISION

UUID from the previous completed checkout of the same repository and target, even if a later build step failed.

VB_PREVIOUS_SUCCESSFUL_REVISION

UUID from the previous finished SUCCESS build of the same repository and target.

History variables are absent when no matching earlier build exists. In a Windows Freestyle batch step, use %VB_REVISION%; in a Linux shell step, use $VB_REVISION.

The Jenkins env-vars.html page describes these variables and when they are available. It does not display the values from an individual build. In Multibranch jobs, BRANCH_NAME identifies the branch job.

Workspace Cleanup

Both options are disabled by default and apply before updating an existing checkout:

  • Revert local changes before checkout restores tracked files and discards pending additions, deletions, and renames. Newly added files remain on disk as untracked files.

  • Clean untracked files before checkout removes untracked files and empty directories, while preserving configured ignore/keep rules and checkout data.

When both are enabled, Revert runs before Clean. Clean alone does not restore modified tracked files; Revert alone does not remove untracked files. In Pipeline, add revertBeforeCheckout: true and/or cleanBeforeCheckout: true to the SCM settings.

Warning

Revert discards local changes, and Clean deletions cannot be undone through the plugin. Use these options only for disposable workspaces. Preserve required build outputs with ignore-glob or keep-glob.

Cleanup does not remove unrelated files to prepare a first checkout; that workspace must still be empty.

Troubleshooting

  • VisionByte is missing: Confirm the plugin and its dependencies are enabled, then restart Jenkins. In Pipeline Syntax, select checkout before looking for VisionByte in the SCM selector.

  • Pipeline is missing from New Item: Install the Jenkins Pipeline plugins.

  • Workspace is not empty or already belongs to a checkout: Choose a fresh workspace outside other VisionByte checkouts, including their parent paths.

  • Authentication fails: Check the username/password credential, its scope and domain, and the account’s repository permissions. Verify access from the build node. For HTTPS errors, check the server certificate and node’s TLS configuration.

  • Runtime cannot be loaded: Check that the build node uses a supported platform, review the full error in Console Output, and restart its JVM after a plugin upgrade.

  • Polling does not trigger a build: Run one manual build, check the schedule and Polling Log, and confirm the node is online. In Pipeline, use poll: true. Check the branch patterns and whether the target is a pinned UUID. For Multibranch, check the scan schedule and scan log.

  • No branch job is created: Confirm the branch is open, matches Branches to discover, and contains a file at the configured Script Path. Run Scan Multibranch Pipeline Now and review the scan log.

  • Jenkinsfile cannot be read: Check Script Path, controller access to the repository, and the selected credentials. Use a supported controller platform, keep its script workspace outside existing checkouts, and clear Lightweight checkout.

  • An old Pipeline snippet is rejected: Use branches: [[name: 'trunk']] instead of the old revision parameter, or regenerate the checkout snippet.

Supported Scope

Version 0.1.0.1 supports one repository and configured target list per ordinary Pipeline build, including reading its Jenkinsfile and checking out the selected version into a build workspace. Each build selects one target. Multibranch Pipeline creates a separate job for each discovered branch.

Lightweight checkout, tag or pull-request discovery, organization folders, webhook triggers, and SSH/private-key authentication are not supported.