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 the most common operational mode, although it is optional. It's currently the only way that your project data can flow to the static and on-demand runners.

If it is not configured, operations will have to run within the CLI so that they have access the project data. This is possible by checking out the source code, having a waypoint.hcl file, and running a command such as waypoint up.

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 git 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 git via the CLI

If you wish to enable git with the CLI instead, you'll want to apply your git settings per project like you would in the UI with the waypoint project apply command. An example of what you would run is shown below:

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

Configuring via waypoint.hcl

If you wish to enable Git inside your project file:

project = "example"

runner {
  enabled = true

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

app "example" {
  // etc
}

Polling

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.

An example of the command you would run to apply polling to your project could be:

waypoint project apply \
   -poll \
   -poll-interval="30s" \
   my-project

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.