Runway Lookups allow the use of variables within the Runway config file. These variables can then be passed along to deployments, modules and tests.

The syntax for a lookup is ${<lookup-name> <query>::<arg-key>=<arg-value>}




Signifies the opening of the lookup.


The name of the lookup you wish to use. (e.g. env)

`` ``

The separator between lookup name a query.


The value the lookup will be looking for. (e.g. AWS_REGION) | When using a lookup on a dictionary/mapping, like for the var lookup, you can get nested values by providing the full path to the value. (e.g. ami.dev}


The separator between a query and optional arguments.


An argument passed to a lookup. Multiple arguments can be passed to a lookup by separating them with a comma (,). Arguments are optional. Supported arguments depend on the lookup being used.

Lookups can be nested (e.g. ${var ami_id.${var AWS_REGION}}).

Lookups can’t resolve other lookups. For example, if i use ${var region} in my Runway config file to resolve the region from my variables file, the value in the variables file can’t be ${env AWS_REGION}. Well, it can but it will resolve to the literal value provided, not an AWS region like you may expect.

Lookup Arguments

Arguments can be passed to Lookups to effect how they function.

To provide arguments to a Lookup, use a double-colon (::) after the query. Each argument is then defined as a key and value seperated with equals (=) and the arguments theselves are seperated with a comma (,). The arguments can have an optional space after the comma and before the next key to make them easier to read but this is not required. The value of all arguments are read as strings.


${var my_query::default=true, transform=bool}
${env MY_QUERY::default=1,transform=bool}

Each Lookup may have their own, specific arguments that it uses to modify its functionality or the value it returns. There is also a common set of arguments that all Lookups accept.

Common Arguments




If the Lookup is unable to find a value for the provided query, this value will be returned instead of raising a ValueError.


Transform the data returned by a Lookup into a different datatype. Supports str and bool.


  - environments:
      some_variable: ${var some_value::default=my_value}
      comma_list: ${var my_list::default=undefined, transform=str}

Build-in Lookups


Retrieve a value from an environment variable.

The value is retrieved from a copy of the current environment variables that is saved to the context object. These environment variables are manipulated at runtime by Runway to fill in additional values such as DEPLOY_ENVIRONMENT and AWS_REGION to match the current execution.


DEPLOY_ENVIRONMENT and AWS_REGION can only be resolved during the processing of a module. To ensure no error occurs when trying to resolve one of these in a Deployment definition, provide a default value.

If the lookup is unable to find an environment variable matching the provided query, the default value is returned or a ValueError is raised if a default value was not provided.


  - modules:
      - path: sampleapp.cfn
          creator: ${env USER}
      ENVIRONMENT: ${env DEPLOY_ENVIRONMENT::default=default}


Retrieve a variable from the variables file or definition.

If the lookup is unable to find an defined variable matching the provided query, the default value is returned or a ValueError is raised if a default value was not provided.

Nested values can be used by providing the full path to the value but, it will not select a list element.

The returned value can contain any YAML support data type (dictionaries/mappings/hashes, lists/arrays/sequences, strings, numbers, and booleon).

  - modules:
      - path: sampleapp.cfn
          ami_id: ${var ami_id.${env AWS_REGION}}
      SOME_VARIABLE: ${var some_variable::default=default}