The Solsta Runner Plugin for TeamCity adds various runner types 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.

Article updated February 15th, 2023 for Solsta TeamCity Plugin version 1.28 or later.

Agent Requirements

In order for TeamCity Agent to execute a runner from this plugin, it must have the following components installed:

• .NET 6.0

Installation

Within your TeamCity server, use the instructions from Installing Additional Plugins to install the Solsta Runner plugin.

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. Restart your TeamCity server after the uninstall (the web UI will prompt you to do this as well).

After the restart, upload the latest Solsta Runner Plugin for TeamCity .zip file, then enable the plugin as you had done during the initial installation. Next, wait for the server to push the latest version of the plugin to your agents. Your agents may be listed under the disconnected section and show “Agent has unregistered (will upgrade)” as a status:

TeamCity recommends waiting up to 10 minutes for agents to be updated. After they receive the latest plugin they will show “connected” again. We recommend reviewing any build steps from the Solsta Runner plugin before executing any new build distributions.

Optional Setup Setup via Solsta Desktop Application

The Solsta Runner 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 how to create those objects using the Solsta Desktop Application.

• Creating Products using Solsta Desktop
• Creating Environments using Solsta Desktop
• Creating Repositories usign Solsta Desktop

Authentication

The Solsta Runner plugin provides three new Runner Types to use as build steps in TeamCity. Each runner type 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 runner deploys (uploads) a new release to the server, bucket or CDN associated with the specified Environment. When creating a Build Step, select Solsta Deploy as the Runner type 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
• 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. 
• 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).

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. 

Solsta Promote

The Solsta Promote runner 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 runner 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 runner 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 

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

License

© Solid State Networks, LLC. All Rights Reserved.

Project status

A project is never done, only released and abandoned.