Users are now able to pass parameters during patch creation and configuration, which are then made available as expansions (i.e. a parameter foo with value bar will replace instances of ${foo} with bar in the project configuration).

This allows projects to maintain non-secret project variables in their project config, rather than the project page, for wider edit/view access. Tests can be written to have different behavior for different parameter values, allowing patches to be more configurable. Parameters can also be used in dynamic variants.

Parameters can be defined in multiple different places, and can overwrite existing project variables. This leads to a specific hierarchy (listed from highest priority to lowest):

• Parameters specified from the patch submission page.

• Parameters passed in from the command-line.

• Project-specific default parameters defined in the user’s local configuration.

• Default parameters defined in the project YAML.

• Project variables defined for the project (Only project admins have access to these).

To define default values for parameters, as well as descriptions, parameters can now be added to the project YAML:

parameters:
    - key: foo
      value: bar
      description: this is a demonstration

Note that value and description are not required. If value is not provided, the default value is the empty string.

If the project configuration is modified, patches will use this value unless overridden through a higher-priority method. For Pull Requests and the Commit Queue, no higher-priority method is available, so modified parameters will be used.

When creating a patch, use --param KEY=VALUE to define each parameter. These will override parameter defaults and project variables, if they exist for the key. Note that the = character is not acceptable in a parameter key or value.

If the user doesn't currently have parameter defaults (and hasn't included --yes to skip prompts), they will receive a prompt to add defaults to their local configuration. Defaults are added to the local configuration as a mapping:

project: 
- name: evergreen
  parameters:
    foo: bar

If defaults are defined here, they will overwrite defaults in the project YAML.

This is the only place where description is used by Evergreen.

evergreen list --parameters --project <project_id> 

This returns the parameters defined in the project's config.

Name      Default       Description
----      -------       -----------
foo       bar           this is a demonstration

If testing local changes, you can use --path <path_to_file> instead of --project.

Parameters can also be retrieved with rest route /projects/<project_id>/parameters, although descriptions are not returned here.

If parameters are defined, they can be seen in the Patch Parameters modal in the patch metadata section. Note that this will only include user-defined parameters, i.e. parameters defined in the project configuration will not be displayed (even if parameter defaults have been modified in the project YAML for this patch). They can also be viewed from the Reconfigure Tasks/Variants Parameters tab (although they will not be modifiable once the patch is scheduled).

If using rest routes to view your patch, parameters will now be included in this document.

If parameters override a private/restricted project variable, are they still private?

• Because parameters are defined in the project configuration or by the user, parameters are not private. This means that if a parameter is overriding a private or restricted project variable, this parameter value will not be private/restricted.

Can parameters be changed after a patch is finalized?

• No, parameters are not configurable after the patch is finalized (i.e. after Schedule Patch is pressed, or --finalize is used when creating the patch from the CLI).

There's another feature I'd like for parameters that doesn't exist. What should I do?

• File a ticket for the Evergreen project! There's room to make parameters even more configurable; if you have a use case that isn't covered let us know!