---
title: "Connect a repository"
description: "Connect an EZGH Git or GitHub repository to a project, choose the bot its tasks run as, and set its trusted refs."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.ezghcloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect a repository

A **connection** ties one repository to a project. Pushes to the repository then run its
`.ezgh/build.yaml` in that project. A repository has one connection.

## In the console

1. **Step 1**

   Open **Build** and choose **Connect repository**.
2. **Step 2**

   Choose the source. **EZGH Git** lists the project's repositories. **GitHub** lists the accounts the
   EZGH Build app is installed on and their repositories; **Install on GitHub** installs the app on an
   account first and returns you to this page. For a GitHub repository, enter its default branch.
3. **Step 3**

   Choose the bot. **Create a bot for this connection** makes one named `build-<repository>`; **Use an
   existing bot** keeps a bot's policies as they are.
4. **Step 4**

   Set the trusted refs (the default branch unless you change them) and choose **Connect repository**.

Connecting needs `build.connections.create`, and for an EZGH Git repository `git.repositories.update`
on it. Making the bot needs `bots.create` and `policies.attach`; adding its trust needs
`bots.updateTrust`.

## With the CLI

```sh
ezgh build connections create --name app --repository app
```

`ezgh build connections create` connects an EZGH Git repository. Without `--bot` it makes the bot;
`--trusted-ref` (repeatable) sets the trusted refs. A GitHub repository is connected in the console.

## The connection's bot

The connection's bot starts each task's sandbox, stores cached results in the project's registry,
reads the repository and reports the checks. A task's script acts as a bot only when the task names
one ([Bots and trust](/build/bots-and-trust)).

A bot made for a connection gets three policies and one trust entry:

| It gets | Which allows |
| --- | --- |
| `SandboxesFullAccess` | Creating, using and deleting sandboxes |
| `RegistryFullAccess` | Pushing, pulling and deleting container images and cached results |
| `GitBuildAccess` | Reading repositories, downloading their files and reporting checks |
| A trust entry for this repository | EZGH Build acting as the bot for commits of this repository, on the refs the entry lists |

The console's entry lists every branch and tag (`refs/heads/**`, `refs/tags/**`), and runs from a
working tree (`refs/local/**`) when you check **Allow runs from a working tree**. The CLI's lists
every ref (`refs/**`). Change the refs on the bot's page in IAM, under **Trusted services**.

An existing bot needs the same access and a trust entry for the repository. Without the entry every
pipeline fails, and the connection's page says so with **Add trust**.

## Trusted refs

A connection's trusted refs are full ref globs such as `refs/heads/main` or `refs/tags/v*`. Pipelines
on them read and write the trusted cache; pipelines on other refs read it and never write it
([Skipping by content](/build/skipping#trusted-refs)).

## What starts a pipeline

- A push to a branch or tag that the file's `trigger` matches.
- `ezgh build run` and `ezgh build rerun` ([Run locally](/build/run-locally)), and **Rerun** on a
  pipeline's page.

Pull requests don't start pipelines of their own: a pull request shows the checks of its head
commit, from the push.

A repository with more than 100,000 files fails its pipeline with "The repository has more than
100,000 files, which EZGH Build can't list".

## Deleting a connection

Deleting a connection cancels its running pipelines; its pipelines and their logs can no longer be
read. The bot, its trust entry and the cached results in the registry are not deleted.

Source: https://docs.ezghcloud.com/build/connect/index.mdx
