|
| 1 | +--- |
| 2 | +title: AI Insights |
| 3 | +description: Understand the Appcircle Build Insights Report - every section and metric returned by the get_build_insights_report MCP tool, and how to generate the visual report with the Appcircle Claude Assistant. |
| 4 | +tags: [appcircle ai, ai insights, build insights] |
| 5 | +sidebar_position: 4 |
| 6 | +--- |
| 7 | + |
| 8 | +import ContentRef from '@site/src/components/ContentRef'; |
| 9 | +import Screenshot from '@site/src/components/Screenshot'; |
| 10 | + |
| 11 | +# AI Insights |
| 12 | + |
| 13 | +Turn your build history into answers. AI Insights reads your CI data and generates the Build Insights Report: trends, root causes, and a maturity score at a glance. |
| 14 | + |
| 15 | +## Build Insights Report |
| 16 | + |
| 17 | +The **Build Insights Report** gives you a snapshot of your CI health: build trends, failure root causes, workflow quality, artifact health, queue time, and an overall maturity score. Use the [Appcircle Claude Assistant](/appcircle-ai/ai-assistants/appcircle-claude-assistant) to get a visual report, or use the [Appcircle MCP client](/appcircle-ai/appcircle-mcp-server) directly. |
| 18 | + |
| 19 | +### How to Generate a Report |
| 20 | + |
| 21 | +**With the Appcircle Claude Assistant** |
| 22 | + |
| 23 | +- Ask in natural language, for example *give me a build insights report for last month* or *how is our CI maturity*. |
| 24 | +- The `appcircle:build-insights-report` skill makes one call to `get_build_insights_report` and renders the response as a report. |
| 25 | + |
| 26 | +**With Any Other MCP Client** |
| 27 | + |
| 28 | +- Call `get_build_insights_report` directly from any MCP-compatible client (Cursor, VS Code, Codex, and so on). |
| 29 | +- You get the same metrics as structured JSON, which you can read, feed into another tool, or visualize yourself. |
| 30 | + |
| 31 | +### Report Sections |
| 32 | + |
| 33 | +The report has six sections. |
| 34 | + |
| 35 | +#### Maturity Assessment |
| 36 | + |
| 37 | +A single CI maturity score (0-100) for the period, with a label of **Developing**, **Practicing**, **Advancing**, or **Optimizing**, and the delta against the previous period. The overall score rolls up four weighted dimensions: |
| 38 | + |
| 39 | +| Dimension | What it measures | |
| 40 | +|---|---| |
| 41 | +| Reliability | Build success rate, mean time to recovery (MTTR), number of flaky build profiles (same commit both passing and failing), and profiles with recurring warning hotspots | |
| 42 | +| Discipline | Workflow completeness against Appcircle's recommended steps, and adherence to configuration best practices | |
| 43 | +| Speed | How consistent build durations are (P95/P50 ratio) and an overall speed score across active profiles | |
| 44 | +| Security | Signing identity health, environment variable group usage, and certificates or provisioning profiles nearing expiry | |
| 45 | + |
| 46 | +Below the scores, a ranked **Top Improvements** list surfaces the highest-impact actions for the period, each with the affected build profiles. Typical items include: |
| 47 | + |
| 48 | +- Resolving flaky profiles |
| 49 | +- Migrating [custom scripts to Git](/workflows/common-workflow-steps/custom-script-from-git) |
| 50 | +- Configuring PR workflows |
| 51 | +- Configuring [environment variable groups](/environment-variables) |
| 52 | +- Renewing [signing identities](/signing-identities) that are close to expiring |
| 53 | + |
| 54 | +<Screenshot url='https://cdn.appcircle.io/docs/assets/AI-110-Build-Insights-Maturity-Assessment.png'/> |
| 55 | + |
| 56 | +#### Health Snapshot & Trends |
| 57 | + |
| 58 | +**Health Snapshot** is a point-in-time view of the period: |
| 59 | + |
| 60 | +- Summary cards for total builds, success rate, failed builds, and canceled/timeout builds, each with the change versus the previous period. |
| 61 | +- **Top active profiles**: the busiest build profiles, with build counts and success rates. |
| 62 | +- **Inactive profiles**: profiles with no builds in the last 30 days, as cleanup or archiving candidates. |
| 63 | +- **Top build activity**: the most active profile/branch combinations. |
| 64 | +- **Top manual and automated triggers**: who is starting the builds and how (manual or trigger). |
| 65 | +- An AI-authored summary of the period's overall volume and success-rate signal. |
| 66 | + |
| 67 | +<Screenshot url='https://cdn.appcircle.io/docs/assets/AI-110-Build-Insights-Health-Snapshot.png'/> |
| 68 | + |
| 69 | +**Trends** plots the same window over time: |
| 70 | + |
| 71 | +- Daily pass rate and fail rate. |
| 72 | +- Daily build volume, broken down by success, failed, canceled, and timeout. |
| 73 | +- Per-profile build duration, both as a chart of median (P50) build time over the period and as a table of P50, P95, the P95/P50 ratio, a trend (faster/stable/slower), and a consistency rating (consistent/moderate/high variance) for each active profile. |
| 74 | + |
| 75 | +<Screenshot url='https://cdn.appcircle.io/docs/assets/AI-110-Build-Insights-Trends.png'/> |
| 76 | + |
| 77 | +#### Root Cause |
| 78 | + |
| 79 | +Failure analysis for the period: |
| 80 | + |
| 81 | +- **Top failing steps**: the workflow steps most responsible for failures, with the profile and branch combinations they failed on most. |
| 82 | +- **Mean time to recovery**: the longest failure-to-success gaps, by profile and branch. |
| 83 | +- **Flaky builds**: profiles and branches where the same commit produced both a pass and a fail, with an estimate of wasted build time. |
| 84 | +- **Warning hotspots**: profiles and branches that repeatedly pass with warnings, and which step triggers them most. |
| 85 | +- **Zero success workflows**: workflows that had runs in the period but never passed, with the step that always failed. |
| 86 | + |
| 87 | +<Screenshot url='https://cdn.appcircle.io/docs/assets/AI-110-Build-Insights-Root-Cause.png'/> |
| 88 | + |
| 89 | +#### Workflow Quality |
| 90 | + |
| 91 | +How well each profile's workflows match Appcircle's recommended flow: |
| 92 | + |
| 93 | +- A completeness score (0-100) for the most active Push workflow and the most active PR workflow per profile, with the workflow name. A profile with no Push or PR workflow configured shows that state explicitly rather than a zero score. |
| 94 | +- A tiered breakdown of missing steps across all evaluated workflows, grouped as **Critical** (must have), **Important** (great to have), and **Advanced** (good to have), each linking out to the relevant Appcircle workflow step documentation. |
| 95 | +- **Best practice checks**: configuration issues found across active profiles, such as custom scripts not sourced from Git, missing PR workflows, or [versioning](/versioning) that is not automated. |
| 96 | + |
| 97 | +<Screenshot url='https://cdn.appcircle.io/docs/assets/AI-110-Build-Insights-Trends-Workflow-Quality.png'/> |
| 98 | + |
| 99 | +#### Artifact Health |
| 100 | + |
| 101 | +- Average primary artifact size per profile for the period, as a ranked bar chart. |
| 102 | +- Call-outs for the profile whose artifact grew the most and the one that shrank the most compared to the previous period (when a previous-period baseline exists). |
| 103 | + |
| 104 | +#### Queue Time |
| 105 | + |
| 106 | +How long builds waited before starting, tree-wide for the period: |
| 107 | + |
| 108 | +- Average, P50, P95, and total wait time, across however many builds had queue data. |
| 109 | +- A daily trend of average wait time. |
| 110 | +- When wait times are elevated or trending up, a recommendation card that names which [machine plan](/infrastructure/machine-plans) absorbed the most wait and suggests an upgrade path (Standard, Velocity, Ultra) or increasing concurrency. |
| 111 | + |
| 112 | +<Screenshot url='https://cdn.appcircle.io/docs/assets/AI-110-Build-Insights-Artifact-Queue.png'/> |
| 113 | + |
| 114 | +### FAQ |
| 115 | + |
| 116 | +#### What's the Default Time Range? |
| 117 | + |
| 118 | +The last 30 days, compared against the 30 days before that for deltas. Pass `start_date` and `end_date` to the tool to use a different window; the tool compares it against a preceding period of the same length. |
| 119 | + |
| 120 | +#### Can I Get This Report Outside the Appcircle Claude Assistant? |
| 121 | + |
| 122 | +Yes, for the underlying data. Any MCP client can call `get_build_insights_report` and get the same metrics as JSON. The visual HTML report rendering shown on this page is produced by the `appcircle:build-insights-report` skill, which is currently exclusive to the [Appcircle Claude Assistant](/appcircle-ai/ai-assistants/appcircle-claude-assistant). |
| 123 | + |
| 124 | +#### Why Is a Section Missing From My Report? |
| 125 | + |
| 126 | +A section can be absent because there was not enough build activity to compute it for the requested period (for example, no builds, no queued builds, or no profiles with a comparable previous period), which is not an error and not a zero value. It can also be absent because your [access token](/appcircle-ai/appcircle-mcp-server#authentication) lacks the required permission for the data that section depends on. Generating the full report requires a token with at least the **Manager** role. Check your token's role permissions if a section you expect to see is consistently absent. |
| 127 | + |
| 128 | +#### Does the Report Include Builds From Sub-Organizations? |
| 129 | + |
| 130 | +Only if you set `include_sub_orgs` to `true` when calling the tool. It defaults to `false`. |
| 131 | + |
| 132 | +#### Why Might Workflow Quality Section Be Missing? |
| 133 | + |
| 134 | +Workflow Quality is computed from profiles that have at least one Push or PR trigger configured. If no profiles in the organization have Push or PR triggers set up, the section is omitted from the report. |
0 commit comments