Knowledgebase

Search:     Advanced search

Surround SCM Jenkins Integration

Article ID: 761  |  Last updated: 13 Jan, 2017

Surround SCM supports integration with Jenkins. See Surround SCM Third-Party Integrations for supported platforms and versions.

This article includes information about the integration requirementsinstalling the plug-inconfiguring projects to use Surround SCM, modifying the executable path for nodes, syncing workspaces, and troubleshooting for the current plug-in version.

Requirements

  • The Surround SCM command line interface (CLI), sscm.exe, must be installed on the same computer as Jenkins.
  • You must have permission to log in to the Surround SCM CLI and to view and get files. 
  • Jenkins 1.580.1 or later must be installed.

Installing the plug-in

  1. Click Manage Jenkins on the Dashboard page and then click Manage Plugins. The Jenkins Plugin Manager page opens.
  2. Click the Available tab and enter 'Surround SCM' in the Filter field.
  3. Select the Seapine Surround SCM Plug-in and click Install without restart. The Installing Plugins/Upgrades page opens and displays the installation progress.
  4. When installation completes, click Go back to the top page to return to the dashboard or select Restart Jenkins when installation is complete and no jobs are running to restart Jenkins.

Configuring projects to use Surround SCM

You can configure Jenkins freestyle projects and pipelines to retrieve files from Surround SCM when builds start.

Freestyle project

  1. Click New Item on the Dashboard page.
  2. Enter a project name, select Freestyle project, and click OK. The project Config page opens.
  3. In the Source Code Management area, select Surround SCM.
  4. Enter the Surround SCM Server name and Server port. If you use RSA key exchange to connect to Surround SCM, select the RSA key file to use instead of entering the server information.
  5. Enter the Branch name and Repository path to sync with your workspace.
  6. Select the Credentials for logging in to Surround SCM or click Add to add new credentials.
  7. Set any additional build options.
  8. Click Save. The project is added to the dashboard.

Pipeline

  1. Click New Item on the Dashboard page.
  2. Enter a project name, select Pipeline, and click OK. The pipeline Config page opens.
  3. In the Pipeline area, select Pipeline script as the Definition.
  4. Enter the pipeline Script.
  5. To generate a command to add to the script that checks out files from Surround SCM during a build, click Pipeline Syntax. The Snippet Generator page opens.
  6. In the Steps area, select a Sample Step to generate an sscm or checkout command to add to the script.
    • To generate a simple Surround SCM command that requires minimal parameters and lets you copy a repository address from Surround SCM to use in the URL parameter, select sscm: Surround SCM. Enter or copy the Repository URL for the repository to sync with the workspace and select your login credentials. Only select an RSA key file if you use RSA key exchange to connect to Surround SCM.
    • To generate a general checkout command for all plug-ins that support pipelines that requires more restrictive parameters, select checkout: General SCM. Select Surround SCM in the SCM field, enter the connection information, and specify the branch and repository to sync with the workspace. Depending on the Jenkins and Surround SCM configurations, you may need to select an RSA key file and add login credentials.
  7. Click Generate Pipeline Script.
  8. Copy the generated command and paste it in the appropriate script line on the pipeline Config page.
  9. Set any additional build and project options.
  10. Click Save. The project is added to the Jenkins dashboard.

Using RSA key files

If you use RSA key exchange to connect to Surround SCM, you must configure projects to use the server settings XML file from your Surround SCM administrator. You can specify the path to the key file on the build computer in each project configuration. You can also add the key file to Jenkins to use it with multiple projects and make it available to build computers.

To specify the key file path for a project:

  1. Select Path to RSA key file in the RSA key file field when configuring a freestyle project or generating a pipeline script step.
  2. Enter the full Path to the XML file.
  3. Save the project.
    When the project builds, the file is used to connect to Surround SCM. If the file is not found, the build fails.

To add a key file to share with multiple projects:

  1. Select RSA key file in the RSA key file field when configuring a freestyle project or generating a pipeline script step.
  2. Click Add and choose Jenkins. The Jenkins Credentials Provider dialog box opens.
  3. Specify the following information.
    • Domain—Select Global credentials (unrestricted).
    • Kind—Select Secret file.
    • Scope—Select Global (Jenkins, nodes, items, all child items, etc).
    • File—Click Choose File to locate the server settings file to add.
    • ID—Enter an ID to identify the Surround SCM connection associated with the file.
    • Description—Enter a description to explain what the file is used for.
  4. Click Add. The file is saved in the global credentials.
  5. Save the project.
    When the project builds, the saved credentials file is used to connect to Surround SCM.

Adding Surround SCM login credentials

When configuring new projects to use Surround SCM, you must add your Surround SCM username and password in Jenkins. You may also need to update credentials if you modify an existing project configuration that uses an earlier version of the Surround SCM plug-in. Saving credentials lets you share login information between projects without needing to manually enter them in plain text for each project.

  1. Click Add next to the Credentials field and choose Jenkins. The Jenkins Credentials Provider dialog box opens.
  2. Specify the following information.
    • Domain—Select Global credentials (unrestricted).
    • Kind—Select Username with password.
    • Scope—Select Global (Jenkins, nodes, items, all child items, etc).
    • Username—Enter your Surround SCM username.
    • Password—Enter your Surround SCM password.
    • ID—Enter an ID to identify the credentials.
    • Description—Enter a description to explain what the credentials are used for.
  3. Click Add. The information is saved in the global credentials.

Modifying the Surround SCM executable path

When the plug-in is installed, a default Surround SCM tool is automatically added to the Jenkins global tool configuration. Jenkins uses this to locate the Surround SCM CLI executable in the system PATH variable when builds run. The executable path is set based on the operating system running on the master node, which is the default build computer. If the master node is running Unix, the path is sscm. If the master node is running Windows, the path is sscm.exe.

If the CLI executable is not available in the system PATH variable, you can specify the full path to it in the default tool configuration.

  1. Click Manage Jenkins on the Dashboard page and then click Global Tool Configuration. The Global Tool Configuration page opens.
  2. In the Surround SCM area, click Surround SCM Installations.
  3. Enter the full Path to sscm executable (e.g., C:\Program Files\Seapine\Surround SCM\sscm.exe on Windows, /usr/bin/sscm on Linux, or /usr/local/bin/sscm on Mac).
  4. Click Save to save the changes.

If you run builds on multiple nodes, you may need to override the executable path for each node if it is different than the path in the default Surround SCM tool configuration.

  1. Click Build Executor Status on the Dashboard page. The Nodes page opens.
  2. Click the node name to override the executable path for and then click Configure. The node Configuration page opens.
  3. In the Node Properties area, change the Home value for the Surround SCM tool to the full path to the Surround SCM CLI executable on the build computer.
  4. Click Save to save the changes.

Syncing workspaces with Surround SCM

The plug-in supports polling, synching, and browsing latest changes. If polling is enabled, Jenkins automatically checks Surround SCM for updated files and starts a build if changes are found. When a build starts, files are recursively retrieved from the Surround SCM repository to the workspace build directory. After the build completes, you can use the Changes and Console Output options to view the changelog and output.

Troubleshooting

Specified server settings file not found

This error can occur on Linux when the user running Jenkins does not have read access to the specified RSA key file or the directory it is stored in on the build computer.

Add the RSA key file to the Jenkins credentials and update the project to use the saved credentials file.

If you cannot add the RSA key file to Jenkins for security purposes, make sure it is stored in a shared location on the build computer and that all Jenkins users can access it. 

Article ID: 761  |   Last updated: 13 Jan, 2017
Tags
Jenkins

Prev   Next
Surround SCM Xcode 4 Integration     Surround SCM Dreamweaver Integration