# Can an AI agent read my CI logs and tell me why a build failed?

Yes, by four routes: Copilot's Explain error button, gh, an agent on an MCP server, or a workflow step. What each reads, what it needs, how far to trust it.

By Grant Unwin, published 2026-11-16. Checked against GitHub's documentation and the Claude Code Action documentation on 2026-11-17. The web page: https://www.runners.io/blog/can-an-ai-agent-read-ci-logs

Yes. An agent can read a failed job’s log and say which step failed and why, by 4 routes: Copilot’s Explain error button on the failed run, the `gh` command pasted to an agent, an agent connected to the logs through an MCP server, or a workflow step that hands the failed job to a model. Treat the explanation as a lead to check against the log, not as a verdict.

**In short**

- Four routes read a failed build: Explain error in GitHub, the gh command, an agent on an MCP server, and a workflow step.
- GitHub's page says to use --log-failed in place of --log to filter the output to the failed steps of a job.
- GitHub's page on Explain error says nothing about how much of the log it reads or how accurate it is.
- Ask the agent for the log line its diagnosis rests on, and find that line in the run yourself.
- Job logs and job and step names are text the pull request controls, so keep the agent's permissions narrow.

## What are the ways an agent reads a build log?

| Route | What it reads | What you need | Can it change anything |
| --- | --- | --- | --- |
| Explain error, in GitHub | The failed run. GitHub's page does not say how much of the log it reads. | A GitHub Copilot plan. GitHub's page says that on the Free plan this counts toward the monthly chat message limit. | It opens a chat and gives instructions. Nothing in the page says it edits anything. |
| The gh command, pasted to an agent | The failed steps of one job. GitHub's page gives gh run view --job JOB\_ID --log and says to use --log-failed instead of --log. | A signed-in gh. GitHub's page says read access to the repository is required for the web steps for viewing logs. | No. |
| An MCP server | GitHub's get\_job\_logs: the end of a log, or every failed job in a run. Ours: get\_job\_logs by tail, line range or search phrase, get\_job\_tests and diagnose\_job. | For GitHub's server, a sign-in or a token, and the actions toolset switched on, since it is not in the default set. For ours, an approval in the browser. | GitHub's actions toolset has a trigger tool, and ours is read-only until write tools are switched on. The MCP server post has the detail. |
| A workflow step | What the job gives it. For Claude Code Action in tag mode, the docs say actions: read lets it see the pull request's workflow runs and their results. | A key for the model. The action can only be triggered by users with write access, and for workflow\_run it checks both the workflow's actor and the actor who started the run it follows. | It can edit and commit, as the job's permissions and its tool list allow. |

## How do I give an agent only the failed step?

A whole log is thousands of lines in which a few matter. GitHub’s page for run logs says to use `--log-failed` in place of `--log` for just the failed steps, and `tail` keeps the last 200 lines of that output. We did not run this, because it calls GitHub’s API with your run:

```bash
gh run view --job JOB_ID --log-failed | tail -n 200
```

Paste the result into the conversation, or let the agent run it. With our server the same step is one call: `diagnose_job` is described as the first call for a failed job, with the verdict, the failing steps and tests, memory use and the log around its last error lines, and every answer says what it could not read, so an agent is not led to read “unknown” as “none”.

## How do I run it as a workflow step when a build fails?

This is a plate we have not run, because it needs a key and a failing workflow of yours: check the [action’s usage guide](https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md) for its current inputs before you use it. Its shape follows the [action’s security page](https://github.com/anthropics/claude-code-action/blob/main/docs/security.md): the action runs on a `workflow_run` that has finished, the job holds `actions: read` and no write permission, so the answer goes to the job’s log, and the prompt contains only the run’s number, never a title or a branch name, which other people write. The action stops before it runs the model if the workflow’s actor, or the actor who started the run it follows, lacks write access, so a run from a fork pull request will not start it. The `additional_permissions` input is the one the usage guide lists for viewing workflow results; its examples have no `workflow_run` case, which is another reason to check.

```yaml
on:
  workflow_run:
    workflows: ["CI"]
    types: [completed]

permissions:
  contents: read
  actions: read

jobs:
  explain:
    if: github.event.workflow_run.conclusion == 'failure'
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          additional_permissions: |
            actions: read
          prompt: |
            Run ${{ github.event.workflow_run.id }} of CI failed.
            Read the logs of its failed jobs and say which step failed and
            why, in five lines. Change nothing.
```

## How far can I trust what it says?

As far as the line it quotes. GitHub’s page on Explain error says nothing about its accuracy or about checking its suggestions, and the other routes are a model reading text, so each can be wrong in a convincing way. Ask the agent for the log line its diagnosis rests on, find that line in the run yourself, and only then change the workflow. A flaky test and a real regression produce the same red mark, and a log cannot always tell them apart.

## What can go wrong when an agent reads a log?

A log is not only your tool’s output. The action’s security page says “Job logs, and job and step names, are text the pull request controls”, so a pull request can put words in front of the agent. Our server returns text that people who can push wrote under a key named `untrusted` and tells the agent to treat it as data. That is a request to a model, not a wall, and the [post on prompt injection](https://www.runners.io/blog/is-it-safe-to-let-an-ai-agent-read-ci-logs) covers what to restrict. To connect an agent to a server, see [the MCP servers for GitHub Actions](https://www.runners.io/blog/mcp-server-for-github-actions) or set up our own [MCP server for GitHub Actions](https://www.runners.io/docs/observability/mcp-server); to find which job failed in the first place, the [job page](https://www.runners.io/docs/observability/jobs) and [log search](https://www.runners.io/docs/observability/log-search) show it without an agent.

If the agent is Claude Code, it does not have to be asked. The [runners.io plugin for Claude Code](https://www.runners.io/claude-code) reads your pull requests’ CI from GitHub with your own login and puts each failed run into the open session, with the `gh run view --log-failed` command for its log, so the agent starts from the failed steps. It needs no runners.io account.

## Sources

- [Troubleshooting workflows (GitHub Docs)](https://docs.github.com/en/actions/monitoring-and-troubleshooting-workflows/troubleshooting-workflows/using-copilot-to-troubleshoot-workflows)
- [Using workflow run logs (GitHub Docs)](https://docs.github.com/en/actions/how-tos/monitor-workflows/use-workflow-run-logs)
- [github/github-mcp-server (README)](https://github.com/github/github-mcp-server)
- [Claude Code Action: security](https://github.com/anthropics/claude-code-action/blob/main/docs/security.md)
- [Claude Code Action: usage](https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md)
- [The runners.io MCP server](https://www.runners.io/docs/observability/mcp-server)
- [The runners.io plugin for Claude Code (README)](https://github.com/runners-io/claude-plugin)

## Frequently asked questions

### Can an AI agent read my CI logs and explain a failure?

Yes. Copilot's Explain error button opens a chat about the failed run, an agent can read a log through the gh command or an MCP server, and a workflow step can hand a failed job to a model. Check its diagnosis against the log.

### How do I give an agent only the failed steps?

GitHub's page for run logs gives gh run view --job JOB\_ID --log and says to use --log-failed in place of --log to filter to failed steps. Pass the agent the end of the output. GitHub's MCP server can also return only failed jobs with get\_job\_logs.

### Does GitHub have a built-in way to explain a failed build?

Yes. Explain error is at the top of the workflow run summary page and in the menu beside a failed check in the merge box. It opens a chat with Copilot. On the Free Copilot plan it counts toward the monthly chat message limit.

### Is it safe to let an agent read my CI logs?

Only with narrow permissions. Job logs and job and step names are text a pull request controls, so a pull request can put words in front of the agent. Give it read-only access, no secrets, and no way to push.
