# gh search code: Search Code Across GitHub

> gh search code finds code across repositories with qualifiers. Reference for --language, --repo, --json, and the rate-limit and auth errors in CI.

Source: https://latchkey.dev/learn/command-reference/gh-search-code  
Updated: 2026-06-30

gh search code finds files containing a query string across GitHub, filtered by language, repo, or path.

Audit and inventory jobs use gh search code to find every place a deprecated API or secret pattern appears across many repositories.

## What it does

gh search code queries GitHub code search for matching files. Qualifiers like --language, --repo, --owner, and --filename narrow the results, and --json returns repository and path fields for scripting.

## Common usage

```Terminal
gh search code "actions/checkout@v3" --language yaml
gh search code "TODO" --repo owner/repo
gh search code "ADD_API_KEY" --owner my-org --json repository,path
```

## Flags

| Flag | What it does |
| --- | --- |
| --language <lang> | Filter by programming language |
| --repo <owner/repo> | Restrict to specific repositories |
| --owner <name> | Restrict to repositories owned by a user or org |
| --filename <name> | Filter by filename |
| -L, --limit <n> | Maximum results to return |
| --json <fields> | Output selected fields as JSON |

## In CI

Set GH_TOKEN. Code search requires authentication; an unauthenticated request is rejected, and the default GITHUB_TOKEN can only search the current repository unless given broader scope. Code search has its own stricter rate limit, so batch and back off in loops.

## Common errors in CI

"gh: To use GitHub CLI in a GitHub Actions workflow, set the GH_TOKEN environment variable" means GH_TOKEN is unset. "HTTP 403: API rate limit exceeded" or "secondary rate limit" means too many searches too fast; add delays. "must be authenticated to use code search" confirms a missing or invalid token.

## Using this in CI

CI checkouts are shallow and detached by default, which changes the answer this command gives you. Commands that read history, branch names, or tags need the checkout configured for it.

```.github/workflows/ci.yml
- uses: actions/checkout@v4
  with:
    fetch-depth: 0   # history, tags, and git describe all need this

- run: |
    git rev-parse --is-shallow-repository   # expect false
    git rev-parse --abbrev-ref HEAD          # prints HEAD when detached
```

> `git rev-parse --abbrev-ref HEAD` returns the literal string `HEAD` on a detached checkout rather than a branch name. On GitHub Actions read `github.ref_name` instead; the git command cannot know what it was checked out for.

## FAQ

### gh search code: Search Code Across GitHub?

Audit and inventory jobs use gh search code to find every place a deprecated API or secret pattern appears across many repositories.

### What it does?

gh search code queries GitHub code search for matching files. Qualifiers like --language, --repo, --owner, and --filename narrow the results, and --json returns repository and path fields for scripting.

### In CI?

Set GH_TOKEN. Code search requires authentication; an unauthenticated request is rejected, and the default GITHUB_TOKEN can only search the current repository unless given broader scope. Code search has its own stricter rate limit, so batch and back off in loops.

### Common errors in CI?

"gh: To use GitHub CLI in a GitHub Actions workflow, set the GH_TOKEN environment variable" means GH_TOKEN is unset. "HTTP 403: API rate limit exceeded" or "secondary rate limit" means too many searches too fast; add delays. "must be authenticated to use code search" confirms a missing or invalid token.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt