Configuration Reference

This document helps you configure the State Tool and your project using the activestate.yaml. The activestate.yaml file looks similar to this:

project: "https://platform.activestate.com/owner/projectName?commitID=00010001-0001-0001-0001-000100010001"
constants:
  - name: LOCATION
    value: world
    if: eq .OS.Name "Linux" # optional
  - name: DBHOST
    value: secrets.user.dbhost
scripts:
  - name: hello-world
    language: bash
    standalone: true # optional
    if: eq .OS.Name "Linux" # optional
    value: echo $constants.LOCATION
  - name: hello-python
    language: python3
    value: |
        import sys
        print(sys.executable)
events:
  - name: activate
    if: eq .Shell "bash" # optional
    value: echo "Welcome to your activated environment!"
  - name: before-command
    scope: [ "command-name" ]
    value: hello-world
  - name: after-command
    scope: [ "command-name" ]
    value: hello-world
  - name: file-changed
    scope: [ "folder1", "folder2" ]
    value: hello-world

Parts of the activestate.yaml

Project

Specifies the full URL to your project on the ActiveState Platform.

The parameters in this URL are automatically updated as you work with your project, but you are also able to manually update them. For example you could change the commitID to an earlier commit to have State tool operate on that commit.

constants

Constants can be used both as variables inside your activestate.yaml as well as to set up environment variables for your activated environments.

You can use the constants you define in other constants, scripts, events, and other configuration fields. The following example defines the same LOCATION constant, and references it in the subsequent entry as $constants.LOCATION. Constants are referenced this way wherever you use them in your activestate.yaml file. Constant names are not case-sensitive.

constants:
  - name: LOCATION
    value: World
  - name: HELLO
    value: Hello $constants.LOCATION

Using configuration values as variables is supported for many different fields, not just constants. You can also wrap your variables in brackets in case you’re using them in more advanced scenarios where the variable parser might otherwise get confused, so for example you could use your constant in the following way:

constants:
  - name: LOCATION
    value: World
  - name: HELLO
    value: Hello ${constants.LOCATION}

Constants automatically become environment variables. So when you state activate with the above example you will be able to see the LOCATION variable under printenv | grep LOCATION

Scripts

Scripts allow you to specify your own scripts that will run within the context of your activated environment.

Name

The script name you specify can be accessed in a variety of ways:

• via state run <script-name>
• simply by invoking <script-name> as a command when you’re in an activated environment
• inside your activestate.yaml by using the ${script.<name>} variable

Language

The language specifies one of the Supported Languages.

Standalone

If specified the script won’t source your runtime environment before being ran.

Value

The value is simply the contents of your script, in whatever language you specified.

Events

Events allow you to specify custom functionality based on certain events within the state tool or your environment.

Activate

The activate event triggers when you activate or source your runtime environment. The contents of the activate event will be evaluated as part of your shell’s RC file (provided your shell supports RC files), allowing you to set up parts of your shell for the use of your project.

This means that the contents of the activate event are shell specific so you may want to use conditionals to create different activate events per shell, eg.

events:
  - name: activate
    if: ne .Shell "cmd"
    value: export MYVAR=foo
  - name: activate
    if: eq .Shell "cmd"
    value: set MYVAR=foo

before-command & after-command

These events are triggered before and after a command is ran.

Scope

The scope contains the list of State Tool commands that this event should trigger on.

To see all available commands run state --help.

For example if you would like to trigger the event before each state install you would use scope: [ "install" ].

Value

The value holds the name of a script that should run when the event is triggered.

file-changed

The file-changed event is triggered as the name suggests; when a file is changed. If specified these events will only trigger while you are in an activated state (ie. you ran state activate).

While in an activated state you can view the logs for file events with state events log.

scope

The scope specifies which folders to watch for file-events on.

value

The value holds the name of a script that should run when a file has changed.

Supplemental

Variables

Most things specified in the activestate.yaml can be accessed throughout as variables. Their structure mimicking their position in the yaml. These variables are formatted either as $variableName or ${variableName}. eg. ${scripts.myScriptName}.

For some usage examples see the Constants section.

In addition to normal variables, you can also access the following data:

• $project.namespace(): the namespace of a project (eg. yourUsername/yourProject)
• $project.name(): the project name
• $project.owner(): the project owner (eg. your username)
• $project.url(): the project URL
• $project.commit(): the current commit ID for the project
• $project.branch(): the project branch name
• $project.path(): the full directory path to the project
• $mixin.user.name: Your username (if authenticated)
• $mixin.user.email: Your email (if authenticated)
• $mixin.user.jwt: Your authentication token (if authenticated)

Secrets

You can access a secret via the $secrets.user.<name> or $secrets.project.<name> variables, depending on whether the secret you want is user or project focussed.

Secrets do not have to exist for you to invoke them as merely invoking them will create them.

They also do not need to hold a value before you start using them, if no value exists you will be prompted for it at the time that the secret is used.

Find out more about secrets and their use-cases.

Supported Languages

In places where you can reference the shell the following values are accepted:

Conditionals

You can optionally specify conditionals for certain entities. These conditionals use Golang templating, for information on how to write your conditionals see the relevant Golang documentation.

Aside from the built-in Golang tempalte functions conditionals can make use of the following additional functions:

• Contains: if: Contains "Hello World" "World"
• HasPrefix: if: HasPrefix "Hello World" "Hel"
• HasSuffix: if: HasPrefix "Hello World" "rld"
• MatchRx: if: MatchRx "\w+" "Hello"

In addition to functions you can also access the following data:

• .Project.Namespace: the namespace of a project (eg. yourUsername/yourProject)
• .Project.Name: the project name
• .Project.Owner: the project owner (eg. your username)
• .Project.Url: the project URL
• .Project.Commit: the current commit ID for the project
• .Project.Branch: the project branch name
• .Project.Path: the full directory path to the project
• .OS.Name: OS name (one of Linux, Windows, MacOS, Unknown)
• .OS.Version.Name: OS free-form version name (varies by OS)
• .OS.Version.Version: Raw OS version string
• .OS.Version.Major: OS version major number
• .OS.Version.Minor: OS version minor number
• .OS.Version.Micro: OS version micro number
• .OS.Architecture: OS architecture (one of i386, x86_64, ARM, unknown)
• .Shell: The current shell name (one of the Supported Languages)
• .Mixin.User.Name: Your username (if authenticated)
• .Mixin.User.Email: Your email (if authenticated)
• .Mixin.User.Jwt: Your authentication token (if authenticated)

Deprecation

The following keys have been deprecated and should be transitioned to their new counterparts.

• constraints: The constraints key has been deprecated in favour of the Conditionals.
• platforms: Platforms were used exclusively as a way to perform constraints and thus have been removed as well. In order to perform conditionals you can instead use the .OS variables covered in the Conditionals section.
• languages: The languages key was only ever used in the schema itself, it did not facilitate any functionality. You should be able to simply remove it.