runner Stanza

The runner stanza configures a project for remote operations, including configuring how to source a project's source code from Git and configuring polling.

The settings in this stanza only take effect when waypoint init -update is called.

The runner stanza is completely optional. The settings specified in the runner stanza can also be specified using the waypoint project apply command or via the UI by creating or modifying a project.

runner {
  enabled = true

  data_source "git" {
    url  = "https://github.com/hashicorp/waypoint-examples.git"
    path = "docker/nodejs"
  }
}

The above example enables remote operations and configures the project to clone data from a GitHub repository.

CLI or UI Configuration

All of the settings in the runner stanza can be specified via the CLI using waypoint project apply or via the UI in the project create or modify screens. This approach is preferable since it avoids having to put secrets in your waypoint.hcl file and makes your waypoint.hcl more portable since it doesn't specify a repository.

An example using the CLI is shown below. The example is admittedly a bit unwieldy and not very user-friendly. The recommended approach is to use the web UI.

$ waypoint project apply \
   -data-source=git \
   -git-auth-type=ssh \
   -git-private-key-path=$HOME/.ssh/id_ed25519 \
   -git-url=git@github.com:hashicorp/waypoint-examples.git \
   -waypoint-hcl=waypoint.hcl \
   my-project

runner Parameters

Required

The runner stanza has no required parameters.

Optional

• enabled (boolean: false) - This must be set to true to enable remote operations from the CLI. This only affects the CLI. Remote operations triggered via Git polling or directly via the API are still allowed.

• data_source (data_source: nil) - Configuration for how to fetch the source for this project, such as from Git.

• poll (poll: nil) - Settings for polling the data source for changes and automatically running waypoint up. By default polling is disabled.

• profile (string: "") - The name of the runner profile to target for the project/app to use for remote operations.

data_source Parameters

Label

The data_source stanza takes a label, which is "git" in the example above. The label of the stanza is the data source type to use. Currently, the only supported value is "git", but this could be extended in the future to support other data source types.

Required Parameters

Git

• url (string) - The URL for the Git repository. This can be any URL supported by git clone. For example: https://github.com/hashicorp/waypoint-examples.git or git@github.com:hashicorp/waypoint-examples.git.

Optional Parameters

Git

• path (string: "") - A relative path within the Git repository where the application is. This is used to determine the path to look for a waypoint.hcl and sets the working directory when executing commands. This defaults to the repository root.

• username (string: "git") - Username for basic auth or SSH. The default value is "git". For GitHub basic auth, this value can be any non-empty value. GitHub basic auth only uses the password.

• password (password: "git") - Password for basic auth. For GitHub, this is typically a personal access token.

• key (string: "") - A PEM-encoded SSH private key to use for SSH authentication. A valid value usually starts with -----BEGIN RSA PRIVATE KEY----- or something similar.

• key_password (string: "") - The password for the SSH private key if it is encrypted. This is only required if the private key is encrypted.

• ref (string: "HEAD") - The Git ref that is pulled for operations on this project. This can be a branch name, tag name, or a fully qualified Git ref such as refs/pulls/1234. This defaults to pulling HEAD, the latest commit on the default branch.

• recurse_submodules (int: 0) - The maximum depth to recursively clone submodules. A value of zero disable submodule cloning. This defaults to zero.

poll Parameters

Optional Parameters

• enabled (boolean: false) - True to enable polling. Polling requires that a valid datasource is configured.

• interval (string: "30s") - The interval between polling for changes. This defaults to 30 seconds.