Forem: Xianpeng Shen

cpp-linter-hooks: The Most Complete pre-commit Solution for C/C++ Projects

Xianpeng Shen — Wed, 20 May 2026 05:11:08 +0000

If you work on Python projects, you've probably used pre-commit — running black, ruff, mypy before every git commit, blocking anything that doesn't meet the standard. This workflow is well-established in the Python ecosystem.

For C/C++ projects, it's a different story.

The official mirrors-clang-format hook only handles formatting. If you want clang-tidy for static analysis, you're on your own. Features like compilation database auto-detection, version pinning, or auto-fix? Not even on the radar.

cpp-linter-hooks fills this gap. It provides both clang-format and clang-tidy hooks in a single pre-commit repo, along with the supporting capabilities that C/C++ projects actually need.

Why Not Just Use mirrors-clang-format?

Here's a quick comparison:

Feature	cpp-linter-hooks	mirrors-clang-format
clang-format	✅	✅
clang-tidy	✅	❌
Inline style string (`--style`)	✅	❌
Tool version pinning (`--version`)	✅	❌ (via rev tag)
Custom `.clang-tidy` config	✅	❌
Compilation database auto-detection	✅	❌
Dry-run mode	✅	❌
Auto-fix (`--fix` for clang-tidy)	✅	❌
Verbose output	✅	❌
Parallel execution (`--jobs`)	✅	❌

mirrors-clang-format does one thing: download a clang-format binary and run it on changed files. If formatting is all you need, it works fine.

But in real-world C/C++ projects, the true headache isn't inconsistent formatting — it's clang-tidy diagnostics: memory leaks, undefined behavior, performance pitfalls. These are exactly the issues worth catching at commit time.

Quick Start

Add this to your .pre-commit-config.yaml:

repos:
  - repo: https://github.com/cpp-linter/cpp-linter-hooks
    rev: v1.4.1
    hooks:
      - id: clang-format
        args: [--style=file]
      - id: clang-tidy
        args: [--checks=.clang-tidy]

Then:

pre-commit install
pre-commit run --all-files

The first run downloads the clang tools from PyPI. Subsequent runs use the cached environment.

Practical Configuration Details

Pin Your Tool Version

An easy detail to miss: rev is the project version of cpp-linter-hooks, not the clang tool version. Without an explicit version, upgrading rev may silently change your clang-format or clang-tidy version, leading to inconsistent results across your team.

Always add --version:

- id: clang-format
  args: [--style=file, --version=21]
- id: clang-tidy
  args: [--checks=.clang-tidy, --version=21]

This locks the tool at clang 21 regardless of project rev upgrades.

Compilation Database

clang-tidy needs compiler flags for accurate static analysis. If your project uses CMake or Meson, generate compile_commands.json and cpp-linter-hooks auto-detects it from common build directories (build/, out/, cmake-build-debug/, etc.) — no extra configuration needed.

You can also specify it explicitly:

- id: clang-tidy
  args: [--compile-commands=build, --checks=.clang-tidy]

To generate the compilation database:

cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -Bbuild .

Auto-Fix

clang-tidy's --fix can auto-apply fixes for certain checks. cpp-linter-hooks supports this since v1.4.0, but it's opt-in — auto-modifying source code carries risk, and you should decide whether you trust it.

- id: clang-tidy
  args: [--checks=.clang-tidy, --fix]

Note: enabling --fix automatically disables parallel execution (--jobs) to prevent concurrent writes to the same header file.

Performance

Running full clang-tidy on a large codebase can be slow. Two ways to optimize:

Limit scope with the files filter:

- id: clang-tidy
  args: [--checks=.clang-tidy, --version=21]
  files: ^(src|include)/.*\.(cpp|cc|cxx|h|hpp)$

Enable parallelism:

- id: clang-tidy
  args: [--checks=.clang-tidy, --jobs=4]

For day-to-day development, you can also check only changed files:

pre-commit run --files $(git diff --name-only)

Relationship with cpp-linter-action

If you've looked into C/C++ CI tooling, you might have seen cpp-linter-action (139 stars on GitHub Marketplace). It's a GitHub Action that runs clang-format and clang-tidy in CI pipelines and surfaces results as file annotations, thread comments, and PR reviews.

cpp-linter-hooks and cpp-linter-action are two complementary tools under the same organization:

cpp-linter-action: runs in CI, designed for the PR review workflow
cpp-linter-hooks: runs locally before git commit, designed for daily development

Both share the same .clang-format and .clang-tidy configuration files. Code that passes locally won't break in CI — a classic "local + CI dual-gate" pattern.

Wrapping Up

cpp-linter-hooks is one of the main projects I maintain under the cpp-linter organization. Since 2022, it has grown to include version pinning, compilation database detection, auto-fix, and parallel execution — covering the core needs of C/C++ projects at the pre-commit stage.

If you develop in C/C++ or maintain a C/C++ open-source project, give it a try. Add it to your .pre-commit-config.yaml, and within minutes you'll have automatic formatting and static analysis running before every commit — no more waiting for CI to go red before fixing things.

GitHub: https://github.com/cpp-linter/cpp-linter-hooks
PyPI: https://pypi.org/project/cpp-linter-hooks/

Issues and feedback are welcome on GitHub.

Building an AI Agent Inside Jira —— A Jira Copilot Implementation Guide

Xianpeng Shen — Wed, 13 May 2026 17:44:23 +0000

Lately I've been getting the same question over and over: how do you build an AI Agent inside Jira, something like GitHub Copilot but for Jira?

I wasn't planning to write about this — the concept didn't seem particularly complex, and I figured anyone with the relevant background could piece it together from the docs. But after being asked enough times, I realized a lot of people genuinely aren't familiar with this area.

I happened to build a similar application inside Jira recently, so here's the full implementation approach.

The guiding principle is simple: use existing services wherever possible. Don't build from scratch.

Let me walk through it step by step.

Step 1: Create a Bot Account

First, you need a dedicated bot. If your company's IT policy allows it, create an account with a short, easy-to-remember name — something like copilot or ai-bot.

What does this account do? It acts as a "trigger." When a user @-mentions this account in a Jira comment, the automation pipeline kicks in. That's why the name should be short and easy to type — you don't want your colleagues typing @very-long-hard-to-spell-username-2026 every time they need something.

This step isn't technically exciting, but it's where the whole flow begins.

Step 2: Set Up Jira Automation

Once the bot account is ready, the next step is configuring Jira Automation. Jira ships with built-in Automation features — no plugins required.

The logic is straightforward:

Monitor the issue comment section
When someone @-mentions your target user (e.g., copilot), immediately fire a webhook

Jira Automation rules are configured visually, no code involved. You set the trigger condition (Comment contains @copilot), then add a "Send webhook" action pointing to your backend service.

The key here: Automation only handles detection and forwarding. It does zero business logic. Think of it as a doorbell — someone presses it, the signal goes out, that's it.

Step 3: Use a Webhook to Trigger the Backend Application

Once the webhook fires, something needs to receive it. I used Jenkins with the Jenkins Generic Webhook Trigger Plugin.

Why Jenkins? Because most teams already have Jenkins running CI/CD. It's existing infrastructure — no need to deploy a new service from scratch.

The setup:

Create a Pipeline Job in Jenkins, configure the Generic Webhook to receive requests from Jira Automation
When the webhook is triggered, the Pipeline launches your backend Application

One thing to get right: the webhook endpoint needs proper security — tokens, source restrictions, parameter validation. You don't want anyone on the internet triggering your Jenkins jobs.

This Application is the core piece you'll build. My own implementation is based on the GitHub Copilot SDK, but the principle is universal — you can use whatever AI platform or SDK you're comfortable with, as long as it can call an LLM via API or CLI.

Step 4: Build a Skills Architecture

This is the most important design decision in the whole system: your Application should not be a monolithic "do-everything" script. Instead, organize AI capabilities through Skills.

My approach is to maintain a dedicated Git repository, structured roughly like this:

ai-agent/
├── app/          # Core application logic
└── skills/       # Skill definitions
    ├── fix-bug/
    │   └── SKILL.md
    ├── draft-release-note/
    │   └── SKILL.md
    ├── analyze-root-cause/
    │   └── SKILL.md
    └── write-tests/
        └── SKILL.md

app/ directory: manages the overall application logic — receiving webhook requests, parsing user intent, dispatching Skills, returning results.
skills/ directory: each Skill is a subdirectory named after the skill, containing a SKILL.md file (capitalized). This file describes, in natural language, what the skill does, what it takes as input, and what it produces as output. For example, draft-release-note/SKILL.md might contain: "Based on recent commit records and Jira issue lists, generate a draft release note in Markdown format."

The benefits of this design are clear:

Decoupled capabilities: adding a new skill just means creating a new subdirectory and SKILL.md file under skills/ — no changes to core Application code.
Version-controlled: Skills files live in a Git repository with full change history and review mechanisms.
Easy collaboration: anyone on the team can submit a new Skill or improve an existing one, without waiting for a developer's schedule.

Each time the Application starts up, it scans the skills/ directory to see what capabilities are available, then decides which Skill to invoke based on user input.

Step 5: The Actual User Experience

Once this system is running, the user experience looks like this:

In any Jira issue's comment section, @-mention your configured user and describe what you need. For example: @copilot generate the release notes for this version
Jira Automation detects the @-mention event and sends a webhook request
Jenkins receives the request and starts the Application
The Application parses user intent and matches it to the appropriate Skill (e.g., draft-release-note)
The AI executes the task according to the Skill definition, then writes the result back as a Jira comment

From the user's perspective, it's just @-mentioning someone and waiting for a reply in Jira — a completely natural interaction pattern.

In my setup, the tasks that work well include: drafting release notes, analyzing build failure causes, generating root cause analysis drafts, suggesting test code based on context, or (with appropriate repository access) making small code changes.

From there, you continuously refine the system — mostly the Skills — to make the outputs more stable and reliable over time.

Step 6: Lessons Learned and Optimization

Getting the system running is step one. The real work is the continuous optimization that follows. Here are a few lessons I've picked up from hands-on experience.

1. Run in containers, not VMs

Your Application should run in containers (Docker / Kubernetes), not traditional VMs. Containers start fast, isolate resources well, scale horizontally, and — importantly — each trigger gets a clean execution environment. VMs can work, but image management, dependency conflicts, and operational overhead are an order of magnitude worse. For an AI Agent that gets triggered frequently and needs quick responses, containers are the clear winner.

2. If a script can do it, don't use AI

This is the most common mistake — throwing every task at the LLM. The reality is, many operations don't need AI at all. For example:

Pulling issue lists from the Jira API, filtering fields, formatting output → plain script.
Parsing webhook requests, extracting key fields, assembling prompts → preprocessing script.
Writing AI results back as Jira comments → still a script.

Let AI handle only what it's best at: understanding and generating text. All other deterministic logic should be handled by scripts. This not only saves money (fewer tokens consumed) but also produces more stable, predictable results. A useful litmus test: if you can express the logic clearly in under 50 lines of script, don't make an LLM guess at it.

3. Design Skills for reuse

Skills aren't disposable. Design them with reuse in mind:

Right-size granularity. A Skill does one thing, but that thing should be general enough — for example, analyze-build-failure should work across multiple projects, not be hardcoded to one repository.
Parameterize. Use input parameters (project name, version number, date range) to adapt to different scenarios, rather than creating a separate Skill for each one.
Composable. Complex tasks can be built by chaining multiple base Skills. A "weekly release report" might be composed of collect-commits + draft-release-note, instead of writing yet another Skill.

4. Follow Skill authoring best practices

The quality of SKILL.md directly determines the quality of AI output. Here are the key points I've learned:

Explicit input/output definitions. Every Skill must clearly state what it receives (fields, format) and what it produces (text, structure). Don't write "analyze the problem"; write "Receive a Jira Issue Key, read its Description and the last 10 Comments, output a root cause analysis in Chinese, under 200 words."
Provide examples. Include an input/output example in SKILL.md. The AI understands your expectations much more accurately with a concrete sample.
Define boundaries. Explicitly tell the AI what NOT to do. For example: "Do not modify original code, only output suggestions", "Do not fabricate information not present in the issue." A Skill without boundaries gives the AI too much room to improvise, and the results are often unreliable.
Test iteratively. Run the same set of test cases against a Skill repeatedly, comparing output quality after each edit to SKILL.md. This is essentially unit testing — except the subject under test is the AI's prompt.

5. Log token consumption for optimization comparison

This is easy to overlook but critically important: in your Application logs, explicitly record the token count for every request (input tokens, output tokens, total tokens).

Why? Because optimization needs a quantifiable metric. You tweak a prompt, restructure a Skill, switch models — how many tokens did those changes save? Without logging, you're judging by feel. With data, a glance at the logs tells you clearly: same task, token consumption dropped from 2000 to 1200 — optimization confirmed.

I recommend logging these fields:

timestamp: request time
skill_name: the matched Skill
model: the model used
input_tokens / output_tokens / total_tokens
latency_ms: total time (network + inference)
user_input: a summary of the original user input (for traceability)

Once this becomes a habit, every change can be validated quickly, and you'll never have to guess which direction to optimize.

Wrap-Up

That's the high-level implementation approach, along with the pitfalls I've hit and the lessons learned along the way. I won't go into specific code or technical details — every company has different tech stacks, permission models, and internal processes, so directly copy-pasting wouldn't work anyway.

But once you understand the workflow behind these six steps, you can absolutely build a similar system with AI assistance, tailored to your own company's reality.

At its core, this isn't anything particularly mysterious. It's essentially creating an AI-capable robot — a "digital colleague" — that operates inside Jira.

Before, you'd @-mention a teammate in Jira and ask them to write release notes, run tests, or fix a bug. Now, you can @-mention this new digital colleague and have it handle those tasks.

And that, I think, is where AI creates real value inside organizations: making the work that used to require endless back-and-forth communication more automatic, more seamless.

Hope this gives you some ideas. If you're building something similar, I'd love to hear about it in the comments.

Thank you for sharing the Conventional Branch.

Xianpeng Shen — Tue, 16 Sep 2025 13:05:31 +0000

Louis Liu

Mar 26 '25

From Conventional Commits to Conventional Branch

#programming #git #github

Comments

3 min read

New Jenkins Plugin: Let AI Explain Your Build Failures

Xianpeng Shen — Fri, 01 Aug 2025 18:00:49 +0000

Recently, I released my first-ever Jenkins plugin – and it's now officially available in the Jenkins Center! 🎉

This plugin makes it possible to analyze build errors with AI directly inside Jenkins, so you no longer need to copy and paste logs into ChatGPT or other tools. Instead, you'll see an "Explain Error" button right in the console output, and you can also use the explainError() step in your pipeline to trigger AI analysis automatically when a build fails.

This is my first contribution to the Jenkins plugin ecosystem. I used to think most things could be handled by pipeline scripts, and there wasn’t much need for custom plugins. But as AI becomes increasingly mainstream, I noticed something surprising: Jenkins still didn’t have a plugin for AI-based error explanation. So, I decided to build one myself.

With the help of AI and some late-night coding sessions, along with several rounds of thorough code review from the Jenkins Hosting team, the plugin finally went live last weekend. 🚀

Introducing the Plugin

Explain Error Plugin is an OpenAI-powered Jenkins plugin that can automatically analyze logs from failed builds and generate easy-to-understand explanations. It works with both Pipeline and Freestyle job types.

GitHub repo: https://github.com/jenkinsci/explain-error-plugin

Demo

👉 Watch the hands-on demo on YouTube — setup, run, and see how AI explains your Jenkins job failures.

Key Features

Feature	Description
✅ One-click console error explanation	Adds an “Explain Error” button to the build log view
✅ Pipeline support	Use `explainError()` in your pipeline scripts
✅ Custom model support	Choose GPT-3.5 or other models
✅ Jenkins CasC compatible	Supports Configuration as Code
✅ Log filtering	Use regex patterns to focus on error content

Requirements

Jenkins version ≥ 2.479.3
Java version ≥ 17
An OpenAI API key (you can get one at OpenAI)

How to Install

Go to Manage Jenkins → Manage Plugins → Available, then search for:

“Explain Error Plugin”

And install it like any other Jenkins plugin.

Configuration

Once installed, head to Manage Jenkins → Configure System and scroll to Explain Error Plugin Configuration to enter your OpenAI settings.

Setting	Description	Default
Enable Explanation	Enable/disable AI explanation	✅ Enabled
API Key	Your OpenAI API key	Required
API URL	OpenAI endpoint	`https://api.openai.com/v1/chat/completions`
AI Model	Model to use	`gpt-3.5-turbo`

Prefer managing Jenkins with Configuration as Code? You can configure it like this:

unclassified:
  explainError:
    enableExplanation: true
    apiKey: "${AI_API_KEY}"
    apiUrl: "https://api.openai.com/v1/chat/completions"
    model: "gpt-3.5-turbo"

How to Use It

In Your Pipeline

Best used in a post { failure { ... } } block so it automatically analyzes failures:

post {
  failure {
    explainError()
  }
}

You can also customize how logs are filtered:

explainError(
  maxLines: 500,
  logPattern: '(?i)(error|failed|exception)'
)

In Console Output

This works for any job type:

Go to the console output of a failed build
Click the “Explain Error” button at the top
The AI-generated explanation will appear below the button

Demo Preview

When a build fails, you’ll see a sidebar entry on the build page where the AI explanation will be shown:

Or you can view the explanation directly on the console page after clicking the “Explain Error” button:

What’s Next

Error caching: Avoid redundant API calls for the same errors (already implemented, pending merge)
Multi-model support: Plan to support other AI services like Gemini, Claude, DeepSeek, etc.

More features are under development or in the idea phase — and your feedback is always welcome!

Final Thoughts

The plugin is 100% open source — contributions and suggestions are very welcome!

If you try the plugin and find it useful, feel free to share this article, or give the project a ⭐ on GitHub:

GitHub: https://github.com/jenkinsci/explain-error-plugin

That’s the best way to support open-source work like this. 🙌

C/C++ Lint Action | clang-format & clang-tidy

Xianpeng Shen — Fri, 26 Nov 2021 13:49:33 +0000

My Workflow

A Github Action for linting C/C++ code integrating clang-tidy and clang-format to collect feedback provided in the form of thread comments and/or annotations.

Submission Category:

Maintainer Must-Haves

Yaml File or Link to Code

cpp-linter / cpp-linter-action

A Github Action for linting C/C++ code integrating clang-tidy and clang-format to collect feedback provided in the form of file-annotations, thread-comments, workflow step-summary, and Pull Request reviews.

C/C++ Linter Action ^{| clang-format & clang-tidy}

A Github Action for linting C/C++ code integrating clang-tidy and clang-format to collect feedback provided in the form of file-annotations, thread-comments workflow step-summary, and Pull Request reviews (with tidy-review or format-review).

Usage

Create a new GitHub Actions workflow in your project, e.g. at .github/workflows/cpp-linter.yml

The content of the file should be in the following format.

    steps:
      - uses: actions/checkout@v5
      - uses: cpp-linter/cpp-linter-action@v2
        id: linter
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          style: 'file'  # Use .clang-format config file
          tidy-checks: '' # Use .clang-tidy config file
          # only 'update' a single comment in a pull request thread.
          thread-comments: ${{ github.event_name == 'pull_request' && 'update' }}
      - name: Fail fast?!
        if: steps.linter.outputs.checks-failed > 0
        run: exit 1

For all explanations of our available input parameters and…

View on GitHub

cpp-linter.yml

name: cpp-linter

on:
  pull_request:
    types: [opened, reopened]  # let PR-synchronize events be handled by push events
  push:

jobs:
  cpp-linter:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: cpp-linter/cpp-linter-action@v2
        id: linter
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          style: file

      - name: Fail fast?!
        if: steps.linter.outputs.checks-failed > 0
        run: |
          echo "Some files failed the linting checks!"
        # for actual deployment
        # run: exit 1

Additional Resources / Info

https://cpp-linter.github.io/cpp-linter-action/

Example

Annotations

Thread Comment