Add docs for configuring environment-based image selection
@@ -48,6 +48,42 @@ built-in help system:
travis-worker --help
```
+### Environment-based image selection configuration
+
+Some backend providers supports image selection based on environment variables.
+The required format uses keys that are prefixed with the provider-specific
+prefix:
+
+- `TRAVIS_WORKER_{UPPERCASE_PROVIDER}_IMAGE_ALIASES`: comma-delimited strings used for
+ looking up full image name strings from other environment variables
+- `TRAVIS_WORKER_{UPPERCASE_PROVIDER}_IMAGE_ALIAS_{UPPERCASE_ALIAS}`: contains
+ an alias name which will be used to look up another environment variable, such
+as when routing multiple languages to the same image
+- `TRAVIS_WORKER_{UPPERCASE_PROVIDER}_IMAGE_{UPPERCASE_ALIAS}`: contains a full image name
+ string to be used by the backend provider
+
+The following example is for use with the Docker backend:
+
+``` bash
+# declare aliases for `dist: trusty`, `os: linux`, and `group: dev`
+export TRAVIS_WORKER_DOCKER_IMAGE_ALIASES=dist_trusty,os_linux,group_dev
+export TRAVIS_WORKER_DOCKER_IMAGE_ALIAS_GROUP_DEV=bionic
+export TRAVIS_WORKER_DOCKER_IMAGE_ALIAS_DIST_TRUSTY=trusty
+export TRAVIS_WORKER_DOCKER_IMAGE_ALIAS_OS_LINUX=trusty
+
+# resolves the above alias of `trusty`
+export TRAVIS_WORKER_DOCKER_IMAGE_TRUSTY=travisci/ci-connie:packer-1420290255-fafafaf
+
+# resolves the above alias of `bionic`
+export TRAVIS_WORKER_DOCKER_IMAGE_BIONIC=registry.business.com/fancy/ubuntu:bionic
+
+# resolves as the fallback default image
+export TRAVIS_WORKER_DOCKER_IMAGE_DEFAULT=travisci/ci-garnet:packer-1410230255-fafafaf
+
+# resolves for `language: ruby`
+export TRAVIS_WORKER_DOCKER_IMAGE_LANGUAGE_RUBY=registry.business.com/travisci/ci-ruby:whatever
+```
+
## Development: Running Travis Worker locally
