Solsta Plugin for QuickBuild

Installation and Usage Instructions

The Solsta Plugin for QuickBuild adds various build steps that use the Solsta 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.  

Article updated June 2024 for Solsta Quickbuild Plugin version 1.39 or later. 

Agent Requirements

In order for a QuickBuild Agent 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 QuickBuild server, use the instructions from Plugin Management to install the Solsta Deployments Plugin.

Updating the Plugin

Use the steps below to update the plugin to a new version: 

  1. Stop your QuickBuild server/service
  2. Replace the existing plugin file in your plugins directory with the latest version. Example: deploy-quickbuild-plugin-1.15_deploy-3.7_direct-6.1.1.jar
  3. Start (or restart) your QuickBuild server/service

Note that updating the plugin will not remove its steps from any of your existing projects or build configurations. 

Within your QuickBuild server UI, navigate to Administration > Plugin Management and find the “Solsta Deployments Plugin” to ensure the latest version is installed. 

Optional Setup via Solsta Desktop Application

The Solsta Plugin for QuickBuild 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 Dekstop Application. Please see the articles below for how to create those objects using the Solsta Desktop Application.

Authentication

The Solsta Plugin provides three new types of build steps in QuickBuild. 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 QuickBuild project, select Solsta CRUD from the Publish sub-section, then fill out the fields corresponding to your desired task. 

Each configuration section starts with an “action” dropdown box with the following options: 

  • No Changes
  • Create
  • Edit
  • Delete


Object Creation

Select the Create action for an object, then write a unique value in either the Product, Environment or Repository Name fields to create a new object with the specified name, description and update path count value (when applicable). Be careful to avoid using duplicate names for objects. You can choose the “No Changes” action to leave objects as they are, or the “Edit” action to update object properties when necessary. 

Note: The friendly names for objects are used in other build steps, as well as the Solsta Desktop Application. 

Object Deletion

When deleting a parent object – such as an Environment – make sure to set the action for child objects (Repository and Release) 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, example: s3://ssn-mycompany/.  You can get this from the Environment Details view of the Solsta Desktop Client, or create a support ticket. 
  • Repository – Friendly name for the Repository. Example: gameclient
  • Repository Description – Friendly description for the Repository
  • Optional checkbox– Determines whether the repository being created or edited is marked as “optional.” Learn more about Optional Repositories. 
  • Release – ID of release to be edited or deleted, example: 5d9e5e05e3d86325559c28968088b4c97df4d9430b8449251ec622e26f4b23c9. Note: The release ID can be retrieved from the Solsta Desktop Application.
  • 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 build step deploys (uploads) a new release to your Solsta storage bucket. When adding a new Build Step, select Solsta Deploy from the Publish sub-section, then fill out the following fields.

Basic Deployment Options

  • Create checkbox – when checked, the Product, Environment and Repository you specify in the respective fields will be automatically created during deployment if they do not already exist.  When unchecked, you must specify existing Products, Environments and Repositories.
  • Product – Target product for deployment
  • Environment – Target environment within containing product
  • Repository – Target repository within containing environment
  • Working Directory – path to folder containing the files to be deployed. Note that the agent running this pipeline must have access to this path. 
  • 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).
  • 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)

Advanced Deployment Options

After configuring the basic 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. 

Solsta Promote

The Solsta Promote build step promotes the selected release from a source Product, Environment and Repository to a target Product, Environment and Repository. You can select the same source and product objects but a different Source Release within the same repository to rollback or roll-forward within the same environment. 

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 during its execution. 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.

  • Source Product – Source product for promotion
  • Source Environment – Source environment within containing product
  • Source Repository – Source repository within containing environment
  • Source Release – Type the release version to be promoted from the source object to the target object. Leaving this field empty results in the latest release being selected.
  • 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 QuickBuild. 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. Click the “+Add” button
  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
  4. Add any arguments to be used when launching the file in the Arguments field. Example: –debug –env=dev
  5. Save your configuration

Edit a Launch Entry 

  1. Click on the Entry Name, File Path or Arguments fields as necessary. 
  2. Make any desired changes
  3. Save your configuration

Delete a Launch Entry 

  1. Check the box alongside an existing Launch Entry
  2. Click on the “X Delete” button 
  3. Save your configuration

Solsta Cleanup

The Solsta Cleanup build 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
  • 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.
  • 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.