Build Config Validation

This page documents the new build config validation feature that is currently in beta.

Beta opt-in #

You can opt in using the repository setting “Build config validation” in the Travis CI UI, or by specifying the version in your .travis.yml file:

version: ~> 1.0

Build config validation #

When active the build config validation feature will validate and normalize any incoming build config sources (e.g. your .travis.yml file and configs from build requests created via API).

It uses a formal config format specification which comes in the well known and well-supported format JSON Schema. This feature replaces any previous linting and validation tooling.

Reference documentation autogenerated from this specification can be found here.

You can try out and check how YAML build config sources will be normalized on the Travis CI build config explorer (experimental).

Validation messages #

Validating build configs produces validation messages that you can review on the respective build’s “View Config” tab in the Travis CI UI.

This gives you direct insights into how your build config has been processed, what issues Travis CI might have found, and how to resolve them.

The messages have 4 severity levels:

  • alert - The build config might be leaking secrets. You should pay special attention to these messages.
  • error - The build config contains severe errors that our system cannot recover from, so it will ignore the respective config sections.
  • warn - The build config contains mistakes that our system can repair. It is safe to ignore these messages.
  • info - The build config parser has made changes to the config that you might want to be informed of. It is safe to ignore these messages.

Validation message types #

This table lists build config validation message types, and explains how to respond to these messages.

Level Key Meaning Action
Alert secure The key expects an encrypted value, but an unencrypted value was given. This might leak credentials. Encrypt the given secret.
Error duplicate_key The key was given multiple times, only the value last one will remain, as defined in YAML. Merge the sections on the given keys into one.
Error invalid_condition The condition could not be parsed. Fix the condition. See Testing Conditions for how to validate conditions locally.
Error invalid_env_var The env var could not be parsed. Fix the env var.
Error invalid_format The value has an invalid format. Fix the format used.
Error invalid_type The section has an invalid type, and cannot be used. Check the documentation on this config section, and use the appropriate YAML type.
Error overwrite Two keys were given that overwrite each other. Use only one of the given keys, and combine their values into one.
Error required The required key has not been given. Specify the key.
Error unknown_value The value is not known. Remove the value, or use the equivalent, known value.
Warn clean_key The key is unknown, and contains special characters. Removing the special characters results in a known key. The known key will be used. Remove the special characters.
Warn clean_value The value is unknown, and contains special characters. Removing the special characters results in a known value. The known value will be used. Remove the special characters.
Warn empty The section was empty, and will be dropped. None needed. In order to remove the message remove the key, or add content.
Warn find_key The key is not known. Instead, another similar key is known, and this is assumed to be a typo. The other key will be used. Fix the typo or remove the key.
Warn find_value The value is not known. Instead, another similar value is known, and this is assumed to be a typo. The other value will be used. Fix the typo or remove the key.
Warn strip_key The key contains whitespace. Removing the special characters results in a known key. The known key will be used. Remove the whitespace.
Warn unexpected_seq The key does not expect a sequence (array, list). This is a common error when working with YAML, so it is assumed that the first entry in the sequence represents the intended configuration. The first value in the sequence will be used. Remove the extra dash that turns the section into a YAML sequence.
Warn unknown_key The key is not known. Remove the key, or use the equivalent, known key.
Warn unknown_var The template variable is not known, and might result in an error or a broken notification. Remove the variable or use the equivalent, known variable.
Info alias_key The key is an alias for another key. The aliased key will be used. None needed. In order to remove the message use the aliased key.
Info alias_value The value is an alias for another value. The aliased value will be used. None needed. In order to remove the message use the aliased value.
Info default The key has not been given, the default value for this key will be used. None needed. In order to remove the message specify a value.
Info deprecated The feature has been deprecated. Follow the instruction indicated by the message.
Info deprecated_key The key has been deprecated. Use the key or resolution mentioned in the message.
Info deprecated_value The value has been deprecated. Use the value or resolution mentioned in the message.
Info downcase The string contains uppercase letters. The downcased version of the string will be used.
Info duplicate The value is duplicated. None needed. In order to remove the message use unique values.
Info edge The feature is an edge feature. None needed. Be aware that the behavior of this feature can change, or go away.
Info skip_allow_failure The build has skipped a jobs allow failure rule because its condition did not match. None needed.
Info skip_exclude The build has skipped a jobs exclude rule because its condition did not match. None needed.
Info skip_import The build has skipped an import because its condition did not match. None needed.
Info skip_job The build has skipped a job because its condition did not match. None needed.
Info skip_notification The build has skipped a notification target because its condition did not match. None needed.
Info skip_stage The build has skipped a stage because its condition did not match. None needed.
Info underscore_key The key contains dashes. Replacing the dashes results in a known key. The known key will be used. Use underscores, not dashes.