# GitHub CLI and Claude Code

> Use gh with Githome repositories, and get Claude Code's pull request badge and CI status for them, by signing gh in to Githome once.

Source: https://git.pkgforge.dev/docs/agents/github-cli

The GitHub CLI (`gh`) works with Githome the way it works with a GitHub Enterprise Server: in a clone of a Githome repository, `gh pr create`, `gh pr view`, `gh pr checks`, `gh pr merge` and the other pull request commands talk to Githome, and so do `gh issue list`, `gh issue create` and the other issue commands. Claude Code uses the same setup to show the pull request of the branch you're on and its CI, because it finds pull requests through gh's sign-in. Both go through Githome's [GraphQL API](https://git.pkgforge.dev/docs/reference/graphql-api) and [REST API](https://git.pkgforge.dev/docs/reference/rest-api).

## Set it up

You need a recent `gh` (Githome is tested with 2.89) and a Githome token. With the [Githome CLI](https://git.pkgforge.dev/docs/accounts/cli-sign-in) signed in, one command signs gh in too:

```sh
githome login
githome auth setup-gh
```

`githome auth setup-gh` runs `gh auth login --hostname git.pkgforge.dev --with-token --git-protocol https` and hands gh your token on its standard input, so the token never shows in your shell history or on screen. gh keeps it in its own credential store.

Without the Githome CLI, create a token under **Settings → Access tokens** (`write` scope, so gh can open and merge pull requests), save it to a file, and give it to gh the same way:

```sh
gh auth login --hostname git.pkgforge.dev --with-token --git-protocol https < ~/githome-token.txt
```

In CI or a container, set the host and token in the environment instead. gh and Claude Code both read them:

```sh
export GH_HOST=git.pkgforge.dev
export GH_ENTERPRISE_TOKEN=...   # from your secret store
```

Check it with `gh api user --hostname git.pkgforge.dev --jq .login`, which prints your login.

## Use gh

In a clone whose `origin` is on Githome, gh picks the host from the remote:

```sh
gh pr create --title "Fix the parser" --body "..." --draft
gh pr view --web
gh pr checks --watch
gh pr ready
gh pr merge --auto --squash
gh issue create --title "The parser drops comments" --label bug
gh issue list --label bug
gh issue close 42 --reason "not planned"
gh run list --workflow ci.yml
gh run view --log-failed
```

| Works | Commands |
| --- | --- |
| Reading | `gh pr view` (with `--json`), `gh pr list`, `gh pr status`, `gh pr checks`, `gh pr diff`, `gh issue list` (with `--label`, `--assignee`, `--author`, `--mention`, `--search`, `--state`), `gh issue view` (with `--comments` and `--json`), `gh issue status`, `gh run list`, `gh run view` (with `--job`, `--log`, `--log-failed` and `--json`), `gh run watch`, `gh workflow list`, `gh workflow view`, `gh repo view`, `gh repo list` (with `--public`, `--private`, `--source`, `--limit`), `gh label list`, `gh release list`, `gh ssh-key list`, `gh api` (REST and `gh api graphql`) |
| Changing | `gh ssh-key add` (with `--title` and `--type signing`) and `gh ssh-key delete`, which keep your keys; Githome does not take a key to sign in or to push yet. `gh repo create` (with `--public`, `--private`, `--description`, `--homepage`), `gh repo fork` (with `--clone` and `--org`), `gh repo sync` of a fork on the server, `gh pr create` (with `--draft`, `--reviewer`, `--assignee`, `--label`, and `--head OWNER:BRANCH` from a fork), `gh pr edit`, `gh pr ready`, `gh pr review` (with `--comment`, `--approve`, `--request-changes`), `gh pr comment`, `gh pr close`, `gh pr reopen`, `gh pr merge` (`--merge`, `--squash`, `--rebase`, `--auto`, `--disable-auto`), `gh issue create` (with `--label`, `--assignee`, `--milestone`), `gh issue edit`, `gh issue comment`, `gh issue close` (with `--reason`), `gh issue reopen`, `gh run rerun` (with `--failed` and `--job`), `gh run cancel`, `gh workflow run` (with `--ref` and `-f` inputs), `gh label create` |
| Not yet | Team reviewers, projects, `gh issue delete`, `lock`, `pin` and `transfer`, `gh run delete`, `gh workflow enable` and `disable`. Use `gh api` with the REST paths for anything else. |

gh changes things with your token's permissions and Githome's rules: branch protection, required checks and reviews, and the [agent guardrails](https://git.pkgforge.dev/docs/agents/overview) apply as they do on the web and over REST. `gh pr merge --auto` turns on Githome's auto-merge, which merges once the required checks pass. When nothing blocks the merge, gh merges at once.

## gh in workflows

The forge CI of git.pkgforge.dev is dormant, so no workflow runs there now. Where CI runs, inside a Githome workflow, gh works with the job's own token, as with `GITHUB_TOKEN` on GitHub. It can do what the job's [`permissions:`](https://git.pkgforge.dev/docs/actions/workflow-permissions) allow: `gh issue list` needs `issues: read`, `gh pr comment` needs `pull-requests: write`, and so on.

```yaml
permissions:
  issues: write
steps:
  - run: gh issue create --title "Nightly build failed" --body "See ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"
    env:
      GH_TOKEN: ${{ github.token }}
```

## Claude Code's pull request badge

Claude Code shows the pull request for the branch a session is on, and follows it as it changes:

- **In the terminal**, the footer shows `PR #12` for the current branch's open pull request.
- **In the Claude desktop app**, the session's pull request chip shows the pull request and its CI. Claude Code reports the branch's pull request when a session starts, and a pull request it opens with `gh pr create` as soon as gh prints its URL.

There's nothing to set up beyond signing gh in. Claude Code treats any host other than github.com as GitHub Enterprise: it reads the remote of the folder it's in, gets the token from `GH_ENTERPRISE_TOKEN` (when `GH_HOST` names the host) or from `gh auth token --hostname git.pkgforge.dev`, and asks Githome's REST and GraphQL APIs for the pull request, its review decision and its CI counts. In the desktop app, the folder has to be one you've trusted.

Sessions in Claude Code on the web (claude.ai/code) and project threads run in Anthropic's cloud and get their pull request cards from Anthropic's GitHub integration, which doesn't reach Githome. Those sessions can still use gh and the [MCP server](https://git.pkgforge.dev/docs/agents/mcp) to open pull requests, and the repository's [Agent setup](https://git.pkgforge.dev/docs/connect/cloud-agents) script sets gh up for them. Checks only exist where CI runs; the forge CI of git.pkgforge.dev is dormant, so no workflow runs there now.

## Troubleshooting

| Symptom | Cause and fix |
| --- | --- |
| gh asks you to run `gh auth login` in a Githome clone | gh has no token for the host. Run `githome auth setup-gh`, or check that `GH_HOST` matches the remote's host. |
| `HTTP 401` from gh | The token expired or was revoked. Create a new one and sign gh in again. |
| `gh pr create` or `gh pr merge` fails with a permission error | The token has the `read` scope only, or you need write access to the repository. |
| No badge in the terminal | The branch has no open pull request, or gh isn't signed in to the host. `gh pr view` in the same folder shows which. |
| `gh auth status` shows most of an older token | gh hides a token only after its last `_`. Tokens Githome creates now have no `_` after `ghome_`; if yours does, create a new one and sign gh in again. |