»Git Integration

A project can be directly associated with a Git repository to enable many features:

  • Track exactly which Git commit is associated with a build, deploy, or release
  • Poll and automatically trigger a waypoint up when changes are detected
  • Manual remote operations

This is an optional integration. If you do not associate a project with a Git repository, you can always execute local operations such as waypoint up by checking out the source code and having a waypoint.hcl file.

»Waypoint Server Requirement

Git Polling requires Waypoint server version 0.3.0 and later. If you are on an older version and wish to take advantage of this feature, follow the upgrade guide to upgrade your Waypoint Server. Note that you will have to manually install a runner in your server if you are upgrading from an old server version. A fresh installation of Waypoint server 0.3.0 will automatically include runners.

»Configuring the Project

The Git repository associated with a project is configured with the data_source stanza in the runner stanza in the waypoint.hcl file. These settings can also be specified via the CLI or web UI.

It is recommended that you configure the Git data source using the CLI or web UI. This avoids tying a Waypoint configuration directly to a single Git repository and also avoids secrets such as Git authentication information to be present in the Waypoint configuration. Learn more about how to configure the Git data source using the CLI or web UI here.

»Add to an existing Waypoint project

If you already have a Waypoint project, you can add Git integration just as you would if you were to start a new one. You'll want to configure Git via the CLI or Web, or include a runner stanza in your waypoint.hcl. Also ensure your Waypoint server is at least 0.3.0 and has runners enabled.

»Configuring via the UI

If you wish to enable Git settings on a project in the UI, you'll want to navigate to the project homepage after running waypoint ui -authenticate. From there, you can click on the settings gear icon on the right to navigate to the project settings. Fill in the requested fields to setup Git on your project. It is recommended that you configure the Git data source using the CLI or web UI.

»Configuring via waypoint.hcl

If you wish to enable Git inside your project file:

project = "example"

runner {
  enable = true

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

app "example" {
  // etc


The project can be configured to poll the Git repository and automatically trigger a waypoint up on any changes. To enable polling, toggle polling to on in the web UI as shown below under Automated Sync:


When polling is first enabled, it'll trigger an immediate poll. Subsequent polling operations will happen according to the poll interval set by the server (typically around 30 seconds).

»Configure via the CLI

You may also enable polling using the -poll and -poll-interval flags on the waypoint project apply command. This is an advanced approach. The UI is the recommended way to enable polling.

»Ref Tracking

The project can be configured to clone a specific Git ref. By default, any remote operations or polling will watch the latest commit of the default branch. However, when configuring Git, you may specify any ref for Waypoint to watch:


The value of this field can be a branch name, a tag name, or a fully qualified Git ref such as refs/pull/1014. When a ref is specified, Waypoint will watch only that ref for changes.

»Debugging Git Integration Failures

For triaging any failures with Git or Waypoint runners, you'll want to look in a couple of places.

»UI Troubleshooting

When clicking on a failed build, deploy, or release, the UI should show logs of what happened and why the previous run has failed. If there's not enough information or context here, you'll want to dig into the Waypoint runner logs to determine what went wrong.

»Server side Troubleshooting

Waypoint uses runners to execute Git operations, build containers, and more. If you are troubleshooting a failure, you'll want to look at the runner logs to see if there's any additional information there. This will depend on what platform you are deploying to.

If you are deploying to Kubernetes, you'll want to look at the Waypoint runner pod logs:

kubectl logs pod/waypoint-runner-7744b58c9b-mvrcb

»More Information

For more information on debugging and troubleshooting Waypoint, please check out the docs for troubleshooting.