Solsta Plugin for Jenkins

Installation and Usage Instructions

444-4441461_jenkins-logo-black-and-white-jenkins-ci-hd_adobe_express

The Solsta Plugin for Jenkins adds various build steps that use the Solid State Networks console tools and Manifest API service to manage your Solsta build ecosystem, deploy releases, configure launch parameters and more. Deploying consists of converting and uploading raw files (assets) to a bucket or CDN in order to make releases available for download by Solsta desktop clients. The plugin supports both Jenkins freestyle and pipeline projects (see below for details).

Article updated June 2024 for Solsta Jenkins Plugin version 1.59 or later. 

Node Requirements

In order for a Jenkins Node to execute a build step from this plugin, it must have the following components installed:

  • .NET 8.0 
  • Linux-based runners require GLIBC 2.35 or greater

Installation

Within your Jenkins server, use the “advanced installation” instructions from Managing Plugins to upload and install the Solsta plugin .hpi file.

Updating the Plugin

If you are updating the plugin from a previous version, we recommend uninstalling the existing plugin first. Uninstalling a plugin will not permanently remove its steps from any of your existing projects.

After the uninstall, upload and install the latest Solsta Plugin for Jenkins .hpi file and then restart your Jenkins server. This is required when installing new plugins and it ensures your server is using the latest version. We recommend reviewing any projects using build steps from the Solsta plugin before executing any new builds or pipelines. 

Optional Setup via Solsta Desktop Application

The Solsta Plugin allows for the creation of Products, Environments and Repositories within the Solsta deployment database as part of the Solsta Create or Solsta Deploy steps, however, those objects can also be created in the Solsta Desktop Application. Please see the articles below for more information:

Authentication

The Solsta Plugin provides four new options to use as build steps in Jenkins. Each build step requires a Client ID and Client Secret from Solid State Networks. These credentials were provided when your company signed up for Solsta. Contact your company’s primary contact with Solid State Networks or open a support ticket for assistance.

Solsta CRUD

The Solsta CRUD step allows you to Create, Read, Update or Delete objects within the Solsta ecosystem. When adding a Build Step within a Jenkins project, select Solsta CRUD and then fill out the fields corresponding to your desired task. 

Each configuration section starts with the following radio buttons: 

  • No Changes
  • Create
  • Edit
  • Delete

Object Creation

Selecting the “Create” button converts the dropdown field to a text box. Writing a unique value in either the Product, Environment or Repository fields will result in the step creating a new object with the specified name, description and update path count value (when applicable). Using an existing name value along with updated property values will edit the existing object’s properties when the pipeline is run. 

Note: The friendly names and descriptions of each object are displayed in other build steps, as well as the Solsta Desktop Application. 

Object Deletion

When deleting a parent object – such as an Environment – the radio buttons for all child objects (Repository and Release) should automatically be set to No Changes. We recommend avoiding multiple object deletions in the same pipeline run. 

Deleting Objects is Not Storage Deletion

When you delete an object in the Solsta Desktop Client or in one of the CI/CD plugins, you are making an API call for the object to be deleted from your database ONLY. This is a required step to have deployed file data deleted from your storage bucket, however, it does not happen automatically. Deleting data from storage only happens as part of the Solsta Cleanup step.

If your goal is to delete files that have been deployed to your storage bucket, we recommend deleting releases only, then running the Solsta Cleanup step on an existing Product, Environment and Repository. Please read the cleanup section below for more information about how the Solsta Cleanup step deletes unused data from storage.

Object Fields

  • Product – Friendly name for the Product. Example: LlamaGame
  • Product Description – Friendly description for the Product
  • Environment – Friendly name for the Environment. Example: dev-nightly
  • Environment Description – Friendly description for the Environment
  • Update Path Count – Number of delta update paths that are automatically created when a release is deployed or promoted to this environment. We recommend leaving this at zero (disabled) unless you have discussed this feature with the Solsta support staff. This value MUST be a zero or a positive integer. See Updates and Deltas in Solsta for more information. 
  • Location – the bucket or origin for the environment being created. Note that this field will only appear when an environment is being created, AND if your organization has multiple deployment buckets configured. 
  • Repository – Friendly name for the Repository. Example: gameclient
  • Repository Description – Friendly description for the Repository
  • Optional Repository – Determines whether the repository being created or edited is marked as “optional.” Learn more about Optional Repositories. 
  • Release – Choose from existing releases to edit or delete. 
  • Filter – Filter for existing releases by typing part of the release version or release ID, then clicking outside of the filter box to execute the search. Note that the Release dropdown will only display 10 results. 
  • Release Notes URL –  Add or edit release notes URL to the selected release. 
  • Verbose Logging – when checked, the step will output verbose debug information during execution. When left unchecked, only status messages are printed to the output log.

Solsta Deploy

The Solsta Deploy step deploys (uploads) a new release to the server, bucket or CDN associated with the specified Environment. When adding a Build Step within a Jenkins project, select Solsta Deploy from the dropdown and then fill out the following fields.

Basic Deployment Options

  • Create checkbox – when checked, the Product, Environment and Repository you specify in the fields below will be automatically created during deployment. When unchecked, you will be picking existing Products, Environments and Repositories using dropdown boxes.
  • Product – Target product for deployment
  • Environment – Target environment within containing product
  • Repository – Target repository within containing environment
  • Release Version – Optional, specify a dynamic environment variable or build parameter to use as a friendly version number within Solsta Desktop Application (e.g. 1.0.12). Environment variables can be specified by using this syntax: ${VARIABLE}
    Examples:
    ${BUILD_ID}
    ${BUILD_TAG}
    ${JOB_NAME}
  • Release Notes URL – Optional, specify a URL to the release notes for the release being deployed. (e.g. https://github.com/honda/civic/releases/tag/2025)
  • Working Directory – relative path to folder within build checkout directory. The contents of the folder and its directory structure will be deployed. You can also specify a full path to the source files, provided the agent running this step has access to it. 

Advanced Deployment Options

After configuring your basic deployment options, you can use any of the optional fields below to further customize your deployments.

  • Sync Attributes – when checked, file attributes such as “read-only” or “executable” recognized by the node/runner will be included in the deployment for the release. The Solsta Desktop Application will apply those attributes when the release is installed or updated. 
  • Sync Timestamps – when checked, the source files’ modified time as read by the node/runner will be included in the deployment for the release. The Solsta Desktop Application will apply those timestamps when the release is installed or updated. 
  • Verbose Logging – when checked, the step will output verbose debug information during execution. When left unchecked, only status messages are printed to the output log.
  • Hidden Files – add an entry for each file, filetype or folder you want the “hidden” file attribute to be applied to when the Solsta Desktop Client installs or updates the release. The path to the file or folder is relative to the root of the specified source directory in the Working Directory value. Wildcards * are supported. Example values for each entry: setttings.ini; *.ini; subfolder/*
  • Executable Files – add an entry for each file, filetype or folder you want the “executable” file attribute to be applied to when the Solsta Desktop Client installs or updates the release. The path to the file or folder is relative to the root of the specified source directory in the Working Directory value. Wildcards * are supported. Example values for each entry: GameClient.app/Contents/MacOS/GameClient; *.exe; libraries/*
  • Included Files – add an entry for each file, filetype or folder you want to be included in the deployment. The path to the file or folder is relative to the root of the specified source directory in the Working Directory value.
    • wildcard character: *
    • wildcard negation character: !
    • Examples: *.jpg; server-files/*;!server-files/runtime/*
  • Excluded Files – add an entry for each file, filetype or folder you want to be excluded from the deployment. The path to the file or folder is relative to the root of the specified source directory in the Working Directory value.
    • wildcard character: *
    • wildcard negation character: !
    • Examples: *.ini; configuration/*
    • In case of a conflict, files in the exclude filter will override those in the in include filter


How to Manage Files from Multiple Repositories in the Same Environment

In Solsta, an environment will typically consist of multiple repositories (independent components) of your game or software product. For example, a “daily-dev” environment could consist of unique iterations of each of the following repositories

  • game client
  • game server
  • dev tools
  • high-resolution assets

When the Solsta Dekstop Application installs this environment on machines, it will re-create the folder structure and files for each repository into a single user-specified installation directory. This means there must not be any overlap between files across repositories. If you want the client to re-create a specific sub-directory for a repository, then you must specify the proper directory when deploying releases within that repository. 

You can use the include and/or exclude filters to accomplish this, or you can specify targeted source directories for each unique repository. For example, when deploying releases to a “mods” repository, you can specify up to the /mods/ folder in the “Working Directory” field of the Solsta Deploy Step. This will make the Solsta Desktop App re-create the structure of the the /mods/ folder as seen below:

If you prefer the Solsta Desktop App to re-create a “mods” folder instead, then you will need to specify the parent directory containing “mods” when you deploy. For example: 

You can go as far up your directory tree as you need during deployment to have the Solsta Desktop App re-create the folder structure for each repository. You will need to make sure files and folders specific to the repository are isolated. Options for excluding or including specific sub-directories are upcoming. 

Pipeline Project Support

The screenshot above shows configuring the plugin in a Jenkins “Freestyle” project. If your Jenkins project is a  “Pipeline” type, you can use the Pipeline Syntax section of Jenkins to generate a snippet for each of the steps available from this plugin. In the Sample Step dropdown, each step from the plugin will be pre-pended by ssn_.

  • ssn_cleanup: Solsta Cleanup
  • ssn_create: Solsta CRUD
  • ssn_deploy: Solsta Deploy
  • ssn_launchfiles: Solsta Configure Launch Files
  • ssn_promote: Solsta Promote


On the Snippet Generator page, select your desired Sample Step and fill out each of the fields. Afterwards, scroll down and click the Generate Pipeline Script button:

From here, you can copy and paste the snippet into your Pipeline deployment script. Of course, you can update it with any dynamic values or environment variables as necessary. Note that environment variables use the following syntax: env.VARIABLENAME. 

Example: 

ssn_deploy consClientId: 'super', consSecret: 'secret', consCreate: 'true', consProduct: 'The Llamas of Us', consEnv: 'Jackson', consRepo: 'clickers', syncAttrib: 'true', syncTimestamps: 'true', version: env.BUILD_ID, workingDir: env.WORKSPACE

Variables for your instance of Jenkins can be found at: {instanceURL}/pipeline-syntax/globals#env

Solsta Promote

The Solsta Promote step promotes the latest release from a source Product, Environment and Repository to a target Product, Environment and Repository. If the source and target Environments have different source location values (buckets or origin servers), the promote step will automatically copy all necessary files from the source location to the target location as part of the promotion step.

Also, if the target environment has an update path count value greater than zero, the promote step will automatically create delta update paths within the target Environment and Repository as part of the promotion step.

  • Source Product – Source product for promotion
  • Source Environment – Source environment within containing product
  • Source Repository – Source repository within containing environment
  • Source Release – Select the release to be promoted from the source object to the target object. 
  • Filter –  Filter for releases to be promoted by typing part of the release version or ID. Note that the Source Release dropdown will only display 10 results, so precise filters will yield targeted results. 
  • Target Product – Target product for promotion
  • Target Environment – Target environment within containing product
  • Target Repository – Target repository within containing environment 
  • Verbose Logging – when checked, the step will output verbose debug information during execution. When left unchecked, only status messages are printed to the output log.

Solsta Configure Launch Files

The Solsta Configure Launch Files step manages which files are launched by the client for a specified environment. Choose values for the Product and Environment fields first, then configure multiple launch entries for that environment. 

  • Product – Product containing the environment to be configured
  • Environment – Environment to configure Launch files for
  • Launch Files – This section allows you to add, modify and remove launch entries for the selected environment. See below for step-by-step instructions. 
  • Verbose Logging – when checked, the step will output verbose debug information during execution. When left unchecked, only status messages are printed to the output log. 

Follow the steps below to add, edit or delete launch entries for an environment. Remember to save your configuration and run the build/pipeline containing the Solsta Configure Launch Files step in order for your changes to take effect. 

Related: How Launch Buttons Work in the Solsta Desktop Application

NOTE: Version 1.10 of the Solsta Desktop Application added the ability to configure launch buttons for an environment via its User Interface. This means you can manage launch buttons from both the Solsta Desktop App or the Configure Launch Files step in the plug-in. While the Solsta UI automatically reads the latest launch button changes for an environment, the plug-in DOES NOT. That is: if you make a change to an Environment’s launch buttons on the Solsta Desktop Application, that change will NOT be automatically reflected when you edit the Configure Launch Files step in Jenkins. For that reason, you must always include a complete list of the latest Launch Button entries for the selected environment when using the Configure Launch step. 

Add a Launch Entry 

  1. Select “Create a new entry” from the Launch Files dropdown
  2. Type in a friendly name in the Entry Name field. This name will be displayed in the Solsta Desktop Application. Example: “Launch Game Client”
  3. Type in the path to the file being launched in the File Path field. Example: GameClient.exe.
    • Note that if the file is in a sub-directory from the root of where the environment is installed, you will need to prepend the file path with the {installDirectory} macro. Example: {installDirectory}system/binaries/GameClient.exe
    • To launch a file that is not an application directory on macOS, use /usr/bin/open as the File Path and {installDirectory}name_of_file.pkg in the Arguments field.  
  4. Add any arguments to be used when launching the file in the Arguments field. Example: –debug –env=dev
  5. Click Submit. This will blank out the fields and default the Launch Files dropdown back to “Create a new entry,” however, your entry will now be available to select from the dropdown. 

Edit a Launch Entry 

  1. Select the friendly launch entry name from the Launch Files dropdown. This populates the rest of the fields with the existing values for the entry. 
  2. Make any edits in the Entry Name, File Path or Arguments fields as necessary. 
  3. Click Submit

Delete a Launch Entry 

  1. Select the friendly launch entry name from the Launch Files dropdown. 
  2. Click Delete

Solsta Cleanup

The Solsta Cleanup step cleans up (deletes) old, unused release data from the origin bucket(s) associated with the specified Product. Unused pieces are determined by comparing piece files in a Product in a given Location with pieces required by all releases in the Product tree. Depending on the size and volume of the releases you have deployed, this can be a lengthy process as it reads and compares all the data for that product on the storage bucket. We recommend this process to be run only as needed at periodic intervals. Pieces less than 24 hours old will not be deleted to avoid deleting pieces from in-progress deployments.

The Solsta Cleanup step requires an existing Product, Environment and Repository in order to determine unused pieces for existing releases. For this reason, we recommend you do NOT delete parent objects if your goal is to delete unused data from your storage bucket. Instead, we recommend deleting releases ONLY, then running the cleanup step. After the Cleanup Step completes, then parent objects – Products, Environment and Repositories – can be deleted. 

Releases can be deleted on the Solsta Desktop Application (version 1.9 or later) or in the Solsta CRUD step. See Delete Objects in the Solsta Desktop Application for more details. 

Solsta Cleanup Fields

  • Product – Target product for cleanup
  • Location – bucket or origin server to check for unused release data
  • Trial Run – Checking this box performs a dry run, listing which files would be deleted without actually deleting them.
  • Verbose Logging – when checked, the step will output verbose debug information during execution. When left unchecked, only status messages are printed to the output log.