---
title: "Bots and trust"
description: "Which bot a task acts as, and how a bot trusts EZGH Build for a repository and its 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.

# Bots and trust

Tasks act as [bots](/iam/bots). EZGH Build has no access of its own to your resources: what a task
can do is what its bot's policies allow.

## Two bots

| Bot | Named in | Used for |
| --- | --- | --- |
| The connection's bot | The [connection](/build/connect) | Starting each task's sandbox, storing cached results, reading the repository, reporting checks |
| A task's bot | The task's `bot` key | What the task's script does: `EZGH_API_KEY`, `ezgh` signed in, the registry login, and the task's `secrets`, `buckets` and `clusters` |

A task with no `bot` has no identity. Its script runs on its inputs and can call nothing in EZGH
Cloud.

A task with a `bot` has `EZGH_API_KEY` set to an API key that acts as the bot. The key stops working
when the task ends, and at the latest 10 minutes after the task's `timeout`. `ezgh` is on the
`PATH`, signed in with it, and Docker's login for the project's registry host is set up
(`DOCKER_CONFIG`).

## Trust

A bot is used by EZGH Build only where the bot says so. A **trust entry** on the bot names:

- the service, EZGH Build;
- one repository, an EZGH Git or GitHub repository that is connected;
- 1 to 20 full ref globs, such as `refs/heads/main`, `refs/tags/v*` or `refs/heads/**`. `*` matches
  within one part of a ref and `**` across parts.

A bot has at most 20 entries. An entry lets EZGH Build act as the bot, with everything the bot's
policies allow, for commits of that repository on those refs, and nowhere else. A run from a working
tree is on `refs/local/<branch>`.

### Add or remove an entry

In the console, open the bot in **IAM**, then **Trusted services**. **Add** takes a connected
repository and the refs, one per line. Adding and removing need `bots.updateTrust`; seeing the list
needs `bots.get`.

Removing an entry stops new tasks from acting as the bot for that repository. Tasks already running
keep their key until they end.

### When a bot doesn't trust a run

A task whose bot has no entry matching the repository and ref fails before its script starts, with:

```text
Bot `prod-deployer` doesn't trust EZGH Build for `storefront` on `refs/heads/feature/checkout`
```

A typical deploy bot trusts `refs/heads/main` only. A pipeline on another branch then can't act as
it, whatever the build file on that branch says.

## Trails

[Trails](/trails) records `CreateBuildApiKey` each time a key is issued to a task and each time one
is refused. `AddBotServiceTrust` and
`RemoveBotServiceTrust` record changes to a bot's trust.

Source: https://docs.ezghcloud.com/build/bots-and-trust/index.mdx
