Solsta GitHub Actions Integration

The YAML snippets below call our predefined Solsta GitHub actions to deploy and promote releases within the Solsta ecosystem. Deploying consists of converting and uploading raw files (assets) to a bucket in order to make releases available for download by Solsta desktop clients. These sample YAML snippets are meant to demonstrate a basic deployment and promotion using the Solsta deployment tools running within a docker container. You can modify these snippets as necessary to fit your GitHub Actions deployment pipeline. 

Article updated February 20th, 2023 for deploy action version 2 or later. 

Runner Requirements

The deployment and promotion actions run within our docker container. They can be run on Linux or Windows agents that support loading docker containers. We recommend using either the “ubuntu-latest” or “windows-latest” shared runners from GitHub. Read more about GitHub-hosted runners.

If you prefer to run these actions in your own runners, they will need to have the following components installed:

  • docker
  • (Windows only) git-bash included in %PATH%. See git-scm.comfor more information. 

Authentication

The Solid State Networks deployment tools require authentication using M2M credentials that 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.

The YAML examples below require the credentials to be set as two repository secrets before executing a pipeline.

  • SNXD_CLIENT_ID
  • SNXD_CLIENT_SECRET

 

These variables can be set in the Settings > Secrets > Actions section of your GitHub repository where they can be protected and masked (see image below for an example). 

Solsta Deploy Action

In the deployment snippet below, custom CI/CD variables are defined for the following:

  • 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. 
  • console_version: Version of the Solsta deployment tools. Do not change this unless instructed to do so by Solsta support staff.
  • scripts_version:Version of Solsta deployment scripts. Do not change this unless instructed to do so by Solsta support staff.
  • release_version: An environment variable or build parameter to use as a version within Solsta (optional)
  • target_product: Target product for deployment
  • target_environment: Target environment within containing product
  • target_repository:  Target repository within containing environment

 

Note that the values for product, environment and repository are case-sensitive. If the specified product, environment and repository do not exist, they will be automatically created.

Insert YAML Snippet
To use this Solsta deployment action, insert the YAML snippet below into your GitHub actions YAML after you build or compile your release(s). As mentioned above, you can adjust this YAML within your pipeline to best suite your needs. The Solsta deployment action only needs to be pointed to the path containing your cooked, ready-to-deploy data (or build artifacts). This can be done by editing the value of the working_directory variable. Note that the docker instance  executing the deployment action needs to have access to the files in that path.
 
Example:
working_directory: /github/workspace/mybuilds/v38.1.2

See the docker container fileystem section on GitHub Docs for more information. 

Solsta Deploy YAML

				
					steps:
- name: Deploy Build Assets from bin/ directory
  uses: snxd/deploy-github-deploy-action@v2
  with:
    working_directory: 'bin/'
    console_version: '6.1.2.84'
    scripts_version: '3.7.30'
    release_version: '1.0'
    target_product: 'llamacraft'
    target_environment: 'dev-nightly'
    target_repository: 'game-client'
    solsta_client_id:  ${{ secrets.SNXD_CLIENT_ID }}
    solsta_client_secret:  ${{ secrets.SNXD_CLIENT_SECRET }}

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. 

Solsa Promote Action

In the promote snippet below, custom CI/CD variables are defined for the following:

  • console_version: Version of the Solsta deployment tools. Do not change this unless instructed to do so by Solsta support staff.
  • scripts_version: Version of the Solsta deployment scripts. Do not change this unless instructed to do so by Solsta support staff.
  • 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

 

Note that the values for product, environment and repository are case-sensitive. This action will promote the release currently assigned from the source Product, Environment and Repository to the target Product, Environment and Repository. If the target environment has an update path count value greater than zero, the process will automatically create delta update paths within the target Environment and Repository as part of the promotion step.

Solsta Promote YAML

				
					steps:
- name: Promote a Release from Dev to QA
  uses: snxd/deploy-github-promote-action@v2
  with:
    console_version: '6.1.2.84'
    scripts_version: '3.7.30
    source_product: 'llamacraft'
    source_environment: 'dev-nightly'
    source_repository: 'game-client'
    target_product: 'llamacraft'
    target_environment: 'qa-internal'
    target_repository: 'game-client'
    solsta_client_id:  ${{ secrets.SNXD_CLIENT_ID }}
    solsta_client_secret:  ${{ secrets.SNXD_CLIENT_SECRET }}

Solsta Launch Files Action

The Solsta Launch Files action manages which files are launched by the client for a specified environment. In the snippet below, custom CI/CD variables are defined for the following:

  • console_version: Version of the Solsta deployment tools. Do not change this unless instructed to do so by Solsta support staff.
  • scripts_version: Version of the Solsta deployment scripts. Do not change this unless instructed to do so by Solsta support staff.
  • target_product: Product containing the environment to be configured (case-sensitive)
  • target_environment: Environment to configure Launch Files for (case-sensitive)
  • launch_file1: Up to 10 sets of launch file entry names, paths, and arguments. Each new variable should be enumerated and incremented by 1. The format for each row is:
("entry name" "path" "arg1 arg2 ...")

See the example below for more details.

Related: How Launch Buttons Work in the Solsta Desktop Application

Launch Macros and macOS Executables
  • Note that if the file being launched 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} Example: {installDirectory}system/binaries/GameClient.exe
  • To launch a file that is not an application directory on macOS, use /usr/bin/openas the File Path and {installDirectory}name_of_file.pkg in the Arguments field.

Solsta Launch Files YAML

				
					steps:
    - name: Launch Files Configuration
      uses: snxd/deploy-github-launchfiles-action@v2
      with:
        console_version: '6.1.2.84'
        scripts_version: '3.7.30'
        target_product: 'llamacraft'
        target_environment: 'dev-nightly'
        solsta_client_id:  ${{ secrets.SNXD_CLIENT_ID }}
        solsta_client_secret:  ${{ secrets.SNXD_CLIENT_SECRET }}
        launch_file1: '("Launch Game Server" "{installDirectory}/binaries/system/server.exe" "--debug --token={custom_variable}")'
        launch_file2: '("macOS sample" "/usr/bin/open" "{installDirectory}game_prereq.pkg")'
        launch_file3: '("Entry Name 3" "/path/to/exec" "arg1 arg2 ...")'