Continuous Integration

Continuous Integration (CI) and Continuous Delivery (CD) are essential practices in modern software development, automating the merging, testing, and deployment of code to ensure the main branch is always deployable. CI/CD enhances collaboration, reduces integration issues, and accelerates release cycles, ensuring high-quality software delivery with greater efficiency and confidence.

You can integrate the State Tool into CI workflows, simplifying runtime integration. This allows you to download custom language runtimes with specific requirements and run scripts throughout the build process, defining reliable processes for building, testing, and deploying software projects.

The process is as follows:

  1. Authorization with the ActiveState Platform
  2. Checkout your code repository which includes your activestate.yaml file
  3. Run tests and build artifacts

For an example dockerfile that installs a basic private runtime into a container see here.

Required environment variables

Before you begin:

The following environment variables can be used in your current CI/CD system. Instruction on how to integrate these variables will be tool-specific.

  • ACTIVESTATE_API_KEY: This API key is used to authenticate the State Tool with the ActiveState Platform, as required, to download language projects, update packages, etc.
  • ACTIVESTATE_CLI_DISABLE_UPDATES set to true to disable the State Tool from auto updates. This will ensure the explicit and repeatability of the State Tool usage.This is only needed when installing a specific version of the State Tool. If you plan to install the latest state version with each CI run then this is not required.

Obtaining your API Key

You can obtain an API key by opening a command prompt and running the following State Tool command:

state export new-api-key <orgname/projectname>

Example response:

Note that this key is not stored by ActiveState. Please store the value for later use as you cannot retrieve it again. XYZjMmMwYTgtZWRkOS00ZGRiLThmMWEtNDM4NjlhNzE0MTI0IkNlUnZpQml12345678910

Copy the long string at the end of the response to use as the ACTIVESTATE_API_KEY environment variable in your CI/CD application (GitHub, GitLab, Docker, etc.)

Using a specific version of the state tool

To set your local installation to a specific State Tool version currently used in your system, enter the following environment variable and set the value to true.

    ACTIVESTATE_CLI_DISABLE_UPDATES

Tips to keep in mind

  • Recommend to create a separate, but sharable, account to generate the API key as it may be shared between different people in your organization. Using a generated key from a personal account may introduce unnecessary security risks.
  • Make sure this new sharable account is a member of the organization with access to the needed runtime.
  • The permission setting of this new account must match the level of access needed for the API key generation (i.e. “Admin”)
  • Sensitive information like an API key should be stored appropriately in a tool-specific manner (Github, Gitlab, Docker, etc.)

Getting your runtime on your local system

Checkout a runtime to a local directory using the following command

state checkout <orgname>/<projectname>

Then initiate use of the runtime with

state use <orgname>/<projectname>

In the event you need a project runtime from a branch while your project is in use

  1. Enter state branch in the parent project to see available branches.
  2. Enter state switch <branchname> to change branches.

The following message will confirm the switch has been successful. More information on branching can be found here.

Successfully switched to branch: <branchname>

The activestate.yaml file

A successful state checkout will generate an activestate.yaml file specific to your project and contain information like the location of the project, included dependencies, the commit of the project, etc. This file will need to be added to your source control in order to incorporate the runtime into your CI processes.

If an activestate.yaml file for your project already exists on your system, running state refresh will update the file to the latest version.

Tips to keep in mind

  • When connected to a GitHub account, the State Tool will auto download the repo on checkout. This may not be the optimal behavior you want for your checkout. To disable this feature, enter the following command (with the --no-clone flag)
state checkout <org/project> <local-path> --no-clone

Testing

To run unit tests, integration tests, or other tests using your newly installed runtime, run the test command using state exec. For example, to run a Python unit test, enter

state exec python3 — -m unittest test_math_utils.py

Concurrent tests can be run with the same runtime from the same path on your local system.

For more resources related to continuous integration see