---
layout: docs
page_title: Git Integration
description: |-
  A project can be directly associated with a Git repository to enable many features such as tracking Git commits, triggering deploys on Git changes, and more.
---

# 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](/docs/projects/remote)

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](/docs/upgrading)
to upgrade your Waypoint Server. Note that you will have to [manually install
a runner](/docs/runner/run-manual#manually-running-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](/docs/waypoint-hcl/runner).
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](/docs/waypoint-hcl/runner#cli-or-ui-configuration).

### 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.](#Waypoint-Server-Requirement)

#### 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](/commands/project-apply#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:

```hcl
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`:

![git-settings](/img/project-git.png)

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`](/commands/project-apply#poll) 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:

![ref-tracking](/img/ref-tracking-git.png)

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](/docs/troubleshooting).
