Solsta Plugin for Jenkins -

Solsta Runner Plugin: Jenkins

Installation and Usage Instructions

The Solsta Plugin for Jenkins adds various build steps that use the Solid State Networks console tools and Manifest API service to deploy and promote releases within the Solsta ecosystem. 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 February 15th, 2023 for Solsta Jenkins Plugin version 1.30 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 6.0

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 during the deployment step, 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 Deploy

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

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).
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.

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.

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_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.

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
Target Product – Target product for promotion
Target Environment – Target environment within containing product
Target Repository – Target repository within containing environment

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.

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.

Add a Launch Entry

Select “Create a new entry” from the Launch Files dropdown
Type in a friendly name in the Entry Name field. This name will be displayed in the Solsta Desktop Application. Example: “Launch Game Client”
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.
Add any arguments to be used when launching the file in the Arguments field. Example: –debug –env=dev
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

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.
Make any edits in the Entry Name, File Path or Arguments fields as necessary.
Click Submit

Delete a Launch Entry

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

Solsta Cleanup

The Solsta Cleanup step cleans up (deletes) old, unused release data from the server, bucket or CDN associated with the specified Environment. Deleting releases is upcoming functionality in the Solsta Desktop Application.

Product – Target product for cleanup
Environment – Target environment within containing product
Trial Run – Checking this box performs a dry run, listing which files would be deleted without actually deleting them.