---
url: https://bishop.agentdeployment.co/running/github.md
description: >-
  Giving the agent its own GitHub credential, limiting what it can reach, and
  pushing with git.
---

# GitHub

An agent that opens pull requests, reads issues, or pushes branches needs a GitHub credential of its own. Without one it borrows whatever login happens to be on the machine, and in a container there's nothing to borrow.

```sh
bishop github setup
```

It takes the token from the [`gh` CLI](https://github.com/cli/cli), offering to run `gh auth login` if you aren't logged in, verifies it against GitHub, and writes `GH_TOKEN` to `.env`. From there it reaches the agent's environment, and `gh` picks it up on its own. `GH_TOKEN` is read at startup, so changing it needs a restart.

The report names the account the token acts as and the scopes it carries, and prints the `gh auth refresh` for any scope the agent needs that's missing. Re-running it checks the token instead of issuing another, so it doubles as a health check in a deploy script. It exits non-zero when GitHub won't accept the token.

## Limiting what the agent can reach

**A token from `gh auth login` acts as you, in every repository you can reach.** To limit the agent instead, create a [fine-grained personal access token](https://github.com/settings/personal-access-tokens) scoped to the repositories it should touch, put it in `.env` as `GH_TOKEN`, and run setup to check it. GitHub reports no scopes for a fine-grained token, so setup says what it can't tell you rather than guessing. Setup never replaces a `GH_TOKEN` already in `.env`.

## Pushing with git

git never reads `GH_TOKEN`, so `git push` still asks for a password until the credential helper is installed. Setup says so when it's missing:

```sh
gh auth setup-git
```

SSH keys cover clone and push, but API calls like `gh pr create` still need the token.

## Keeping your own login

**`gh auth login` replaces whichever account the `gh` CLI is signed in as.** On a machine where you're signed in as yourself, `--temporary` runs the login in a `gh` configuration directory it creates and deletes, so your own login survives:

```sh
bishop github setup --temporary
```

The token still lands in `.env`. Because the temporary directory has no account in it, this always logs in rather than reusing one, and it needs a terminal. A `GH_TOKEN` already in `.env` is checked as usual and no login happens at all.

## Secrets somewhere else

For a deployment whose secrets live somewhere other than a `.env` file, `--print` writes the credential to stdout as JSON and nothing to disk, with the report and any prompting on stderr:

```
$ bishop github setup --print
{"GH_TOKEN":"gho_..."}
```

`--no-prompt` never offers the login, and fails with the command to run instead. `--temporary` and `--print` combine: log in as the agent, pipe the token into a secret store, leave nothing behind.

## With the sandbox on

The [sandbox](/running/sandbox) keeps the agent out of `~/.ssh` and the `gh` CLI's login. `bishop nono setup` writes a profile that grants both, so a sandboxed agent can still push.