Skip to content

Connect a repository

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

Updated View as Markdown

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

Open Build and choose Connect repository.

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.

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.

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

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).

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).

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), 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.

Navigation

Type to search…

↑↓ navigate↵ selectEsc close