guide: code quality checks (#23595)

## Description
- Adds guide for AI-powered code quality checks w/ E2B and Docker MCP
- Provides a full e2e tutorial to build a code quality check workflow w/
customization options
- Adds troubleshooting page

## Related issues or tickets
https://docker.atlassian.net/browse/ENGDOCS-3073
This commit is contained in:
Sarah Sanders
2025-10-23 10:15:07 -04:00
committed by GitHub
parent 6c64ad4df3
commit 17ff955196
7 changed files with 2177 additions and 3 deletions

View File

@@ -13,7 +13,7 @@
"no-space-in-code": true,
"no-space-in-links": true,
"no-empty-links": true,
"ol-prefix": {"style": "one_or_ordered"},
"ol-prefix": false,
"no-reversed-links": true,
"reference-links-images": {
"shortcut_syntax": false

View File

@@ -4,9 +4,9 @@ summary: Simplify user access while ensuring security and efficiency in Docker.
description: A guide for managing roles, provisioning users, and optimizing Docker access with tools like SSO and activity logs.
tags: [admin]
params:
featured: true
featured: false
time: 20 minutes
image:
image:
resource_links:
- title: Overview of Administration in Docker
url: /admin/

View File

@@ -0,0 +1,56 @@
---
title: How to build an AI-powered code quality workflow with SonarQube and E2B
linkTitle: Build an AI-powered code quality workflow
summary: Build AI-powered code quality workflows using E2B sandboxes with Docker's MCP catalog to automate GitHub and SonarQube integration.
description: Learn how to create E2B sandboxes with MCP servers, analyze code quality with SonarQube, and generate quality-gated pull requests using GitHub—all through natural language interactions with Claude.
tags: [devops]
params:
featured: true
time: 40 minutes
image:
resource_links:
- title: E2B Documentation
url: https://e2b.dev/docs
- title: Docker MCP Catalog
url: https://hub.docker.com/mcp
- title: Sandboxes
url: https://docs.docker.com/ai/mcp-catalog-and-toolkit/sandboxes/
---
This guide demonstrates how to build an AI-powered code quality workflow using
[E2B sandboxes](https://e2b.dev/docs) with Dockers MCP catalog. Youll create
a system that automatically analyzes code quality issues in GitHub repositories
using SonarQube, then generate pull requests with fixes.
## What you'll build
Youll build a Node.js script that spins up an E2B sandbox, connects GitHub and
SonarQube MCP servers, and uses Claude Code to analyze code quality and propose
improvements. The MCP servers are containerized and run as part of the E2B
sandbox.
## What you'll learn
In this guide, you'll learn:
- How to create E2B sandboxes with multiple MCP servers
- How to configure GitHub and SonarQube MCP servers for AI workflows
- How to use Claude Code inside sandboxes to interact with external tools
- How to build automated code review workflows that create quality-gated
pull requests
## Why use E2B sandboxes?
Running this workflow in E2B sandboes provides several advantages over
local execution:
- Security: AI-generated code runs in isolated containers, protecting your
local environment and credentials
- Zero setup: No need to install SonarQube, GitHub CLI, or manage dependencies
locally
- Scalability: Resource-intensive operations like code scanning run in the
cloud without consuming local resources
## Learn more
Read Docker's blog post: [Docker + E2B: Building the Future of Trusted AI](https://www.docker.com/blog/docker-e2b-building-the-future-of-trusted-ai/).

View File

@@ -0,0 +1,181 @@
---
title: Customize a code quality check workflow
linkTitle: Customize workflow
summary: Adapt your GitHub and SonarQube workflow to focus on specific quality issues, integrate with CI/CD, and set custom thresholds.
description: Learn how to customize prompts for specific quality issues, filter by file patterns, set quality thresholds, and integrate your workflow with GitHub Actions for automated code quality checks.
weight: 20
---
Now that you understand the basics of automating code quality workflows with
GitHub and SonarQube in E2B sandboxes, you can customize the workflow
for your needs.
## Focus on specific quality issues
Modify the prompt to prioritize certain issue types:
{{< tabs group="language" >}}
{{< tab name="TypeScript" >}}
```typescript
const prompt = `Using SonarQube and GitHub MCP tools:
Focus only on:
- Security vulnerabilities (CRITICAL priority)
- Bugs (HIGH priority)
- Skip code smells for this iteration
Analyze "${repoPath}" and fix the highest priority issues first.`;
```
{{< /tab >}}
{{< tab name="Python" >}}
```python
prompt = f"""Using SonarQube and GitHub MCP tools:
Focus only on:
- Security vulnerabilities (CRITICAL priority)
- Bugs (HIGH priority)
- Skip code smells for this iteration
Analyze "{repo_path}" and fix the highest priority issues first."""
```
{{< /tab >}}
{{< /tabs >}}
## Integrate with CI/CD
Add this workflow to GitHub Actions to run automatically on pull requests:
{{< tabs group="language" >}}
{{< tab name="TypeScript" >}}
```yaml
name: Automated quality checks
on:
pull_request:
types: [opened, synchronize]
jobs:
quality:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: "18"
- run: npm install
- run: npx tsx 06-quality-gated-pr.ts
env:
E2B_API_KEY: ${{ secrets.E2B_API_KEY }}
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
SONARQUBE_TOKEN: ${{ secrets.SONARQUBE_TOKEN }}
GITHUB_OWNER: ${{ github.repository_owner }}
GITHUB_REPO: ${{ github.event.repository.name }}
SONARQUBE_ORG: your-org-key
```
{{< /tab >}}
{{< tab name="Python" >}}
```yaml
name: Automated quality checks
on:
pull_request:
types: [opened, synchronize]
jobs:
quality:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: "3.8"
- run: pip install e2b python-dotenv
- run: python 06_quality_gated_pr.py
env:
E2B_API_KEY: ${{ secrets.E2B_API_KEY }}
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
SONARQUBE_TOKEN: ${{ secrets.SONARQUBE_TOKEN }}
GITHUB_OWNER: ${{ github.repository_owner }}
GITHUB_REPO: ${{ github.event.repository.name }}
SONARQUBE_ORG: your-org-key
```
{{< /tab >}}
{{< /tabs >}}
## Filter by file patterns
Target specific parts of your codebase:
{{< tabs group="language" >}}
{{< tab name="TypeScript" >}}
```typescript
const prompt = `Analyze code quality but only consider:
- Files in src/**/*.js
- Exclude test files (*.test.js, *.spec.js)
- Exclude build artifacts in dist/
Focus on production code only.`;
```
{{< /tab >}}
{{< tab name="Python" >}}
```python
prompt = """Analyze code quality but only consider:
- Files in src/**/*.js
- Exclude test files (*.test.js, *.spec.js)
- Exclude build artifacts in dist/
Focus on production code only."""
```
{{< /tab >}}
{{< /tabs >}}
## Set quality thresholds
Define when PRs should be created:
{{< tabs group="language" >}}
{{< tab name="TypeScript" >}}
```typescript
const prompt = `Quality gate thresholds:
- Only create PR if:
* Bug count decreases by at least 1
* No new security vulnerabilities introduced
* Code coverage does not decrease
* Technical debt reduces by at least 15 minutes
If changes do not meet these thresholds, explain why and skip PR creation.`;
```
{{< /tab >}}
{{< tab name="Python" >}}
```python
prompt = """Quality gate thresholds:
- Only create PR if:
* Bug count decreases by at least 1
* No new security vulnerabilities introduced
* Code coverage does not decrease
* Technical debt reduces by at least 15 minutes
If changes do not meet these thresholds, explain why and skip PR creation."""
```
{{< /tab >}}
{{< /tabs >}}
## Next steps
Learn how to troubleshoot common issues.

View File

@@ -0,0 +1,348 @@
---
title: Troubleshoot code quality workflows
linkTitle: Troubleshoot
summary: Resolve common issues with E2B sandboxes, MCP server connections, and GitHub/SonarQube integration.
description: Solutions for MCP tools not loading, authentication errors, permission issues, workflow timeouts, and other common problems when building code quality workflows with E2B.
weight: 30
---
This page covers common issues you might encounter when building code quality
workflows with E2B sandboxes and MCP servers, along with their solutions.
If you're experiencing problems not covered here, check the
[E2B documentation](https://e2b.dev/docs).
## MCP tools not available
Issue: Claude reports `I don't have any MCP tools available`.
Solution:
1. Verify you're using the authorization header:
```plaintext
--header "Authorization: Bearer ${mcpToken}"
```
2. Check you're waiting for MCP initialization:
{{< tabs group="language" >}}
{{< tab name="TypeScript" >}}
```typescript
await new Promise((resolve) => setTimeout(resolve, 1000));
```
{{< /tab >}}
{{< tab name="Python" >}}
```python
await asyncio.sleep(1)
```
{{< /tab >}}
{{< /tabs >}}
3. Ensure credentials are in both `envs` and `mcp` configuration:
{{< tabs group="language" >}}
{{< tab name="TypeScript" >}}
```typescript
const sbx = await Sandbox.betaCreate({
envs: {
ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY!,
GITHUB_TOKEN: process.env.GITHUB_TOKEN!,
SONARQUBE_TOKEN: process.env.SONARQUBE_TOKEN!,
},
mcp: {
githubOfficial: {
githubPersonalAccessToken: process.env.GITHUB_TOKEN!,
},
sonarqube: {
org: process.env.SONARQUBE_ORG!,
token: process.env.SONARQUBE_TOKEN!,
url: "https://sonarcloud.io",
},
},
});
```
{{< /tab >}}
{{< tab name="Python" >}}
```python
sbx = await AsyncSandbox.beta_create(
envs={
"ANTHROPIC_API_KEY": os.getenv("ANTHROPIC_API_KEY"),
"GITHUB_TOKEN": os.getenv("GITHUB_TOKEN"),
"SONARQUBE_TOKEN": os.getenv("SONARQUBE_TOKEN"),
},
mcp={
"githubOfficial": {
"githubPersonalAccessToken": os.getenv("GITHUB_TOKEN"),
},
"sonarqube": {
"org": os.getenv("SONARQUBE_ORG"),
"token": os.getenv("SONARQUBE_TOKEN"),
"url": "https://sonarcloud.io",
},
},
)
```
{{< /tab >}}
{{< /tabs >}}
4. Verify your API tokens are valid and have proper scopes.
## GitHub tools work but SonarQube doesn't
Issue: GitHub MCP tools load but SonarQube tools don't appear.
Solution: SonarQube MCP server requires GitHub to be configured simultaneously.
Always include both servers in your sandbox configuration, even if you're only
testing one.
{{< tabs group="language" >}}
{{< tab name="TypeScript" >}}
```typescript
// Include both servers even if only using one
const sbx = await Sandbox.betaCreate({
envs: {
ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY!,
GITHUB_TOKEN: process.env.GITHUB_TOKEN!,
SONARQUBE_TOKEN: process.env.SONARQUBE_TOKEN!,
},
mcp: {
githubOfficial: {
githubPersonalAccessToken: process.env.GITHUB_TOKEN!,
},
sonarqube: {
org: process.env.SONARQUBE_ORG!,
token: process.env.SONARQUBE_TOKEN!,
url: "https://sonarcloud.io",
},
},
});
```
{{< /tab >}}
{{< tab name="Python" >}}
```python
# Include both servers even if only using one
sbx = await AsyncSandbox.beta_create(
envs={
"ANTHROPIC_API_KEY": os.getenv("ANTHROPIC_API_KEY"),
"GITHUB_TOKEN": os.getenv("GITHUB_TOKEN"),
"SONARQUBE_TOKEN": os.getenv("SONARQUBE_TOKEN"),
},
mcp={
"githubOfficial": {
"githubPersonalAccessToken": os.getenv("GITHUB_TOKEN"),
},
"sonarqube": {
"org": os.getenv("SONARQUBE_ORG"),
"token": os.getenv("SONARQUBE_TOKEN"),
"url": "https://sonarcloud.io",
},
},
)
```
{{< /tab >}}
{{< /tabs >}}
## Claude can't access private repositories
Issue: "I don't have access to that repository".
Solution:
1. Verify your GitHub token has `repo` scope (not just `public_repo`).
2. Test with a public repository first.
3. Ensure the repository owner and name are correct in your `.env`:
{{< tabs group="language" >}}
{{< tab name="TypeScript" >}}
```plaintext
GITHUB_OWNER=your_github_username
GITHUB_REPO=your_repository_name
```
{{< /tab >}}
{{< tab name="Python" >}}
```plaintext
GITHUB_OWNER=your_github_username
GITHUB_REPO=your_repository_name
```
{{< /tab >}}
{{< /tabs >}}
## Workflow times out or runs too long
Issue: Workflow doesn't complete or Claude credits run out.
Solutions:
1. Use `timeoutMs: 0` (TypeScript) or `timeout_ms=0` (Python) for complex workflows to allow unlimited time:
{{< tabs group="language" >}}
{{< tab name="TypeScript" >}}
```typescript
await sbx.commands.run(
`echo '${prompt}' | claude -p --dangerously-skip-permissions`,
{
timeoutMs: 0, // No timeout
onStdout: console.log,
onStderr: console.log,
},
);
```
{{< /tab >}}
{{< tab name="Python" >}}
```python
await sbx.commands.run(
f"echo '{prompt}' | claude -p --dangerously-skip-permissions",
timeout_ms=0, # No timeout
on_stdout=print,
on_stderr=print,
)
```
{{< /tab >}}
{{< /tabs >}}
2. Break complex workflows into smaller, focused tasks.
3. Monitor your Anthropic API credit usage.
4. Add checkpoints in prompts: "After each step, show progress before continuing".
## Sandbox cleanup errors
Issue: Sandboxes aren't being cleaned up properly, leading to resource exhaustion.
Solution: Always use proper error handling with cleanup in the `finally` block:
{{< tabs group="language" >}}
{{< tab name="TypeScript" >}}
```typescript
async function robustWorkflow() {
let sbx: Sandbox | undefined;
try {
sbx = await Sandbox.betaCreate({
// ... configuration
});
// ... workflow logic
} catch (error) {
console.error("Workflow failed:", error);
process.exit(1);
} finally {
if (sbx) {
console.log("Cleaning up sandbox...");
await sbx.kill();
}
}
}
```
{{< /tab >}}
{{< tab name="Python" >}}
```python
async def robust_workflow():
sbx = None
try:
sbx = await AsyncSandbox.beta_create(
# ... configuration
)
# ... workflow logic
except Exception as error:
print(f"Workflow failed: {error}")
sys.exit(1)
finally:
if sbx:
print("Cleaning up sandbox...")
await sbx.kill()
```
{{< /tab >}}
{{< /tabs >}}
## Environment variable not loading
Issue: Script fails with "undefined" or "None" for environment variables.
Solution:
{{< tabs group="language" >}}
{{< tab name="TypeScript" >}}
1. Ensure `dotenv` is loaded at the top of your file:
```typescript
import "dotenv/config";
```
2. Verify the `.env` file is in the same directory as your script.
3. Check variable names match exactly (case-sensitive):
```typescript
// .env file
GITHUB_TOKEN = ghp_xxxxx;
// In code
process.env.GITHUB_TOKEN; // Correct
process.env.github_token; // Wrong - case doesn't match
```
{{< /tab >}}
{{< tab name="Python" >}}
1. Ensure `dotenv` is loaded at the top of your file:
```python
from dotenv import load_dotenv
load_dotenv()
```
2. Verify the `.env` file is in the same directory as your script.
3. Check variable names match exactly (case-sensitive):
```python
# .env file
GITHUB_TOKEN=ghp_xxxxx
# In code
os.getenv("GITHUB_TOKEN") # ✓ Correct
os.getenv("github_token") # ✗ Wrong - case doesn't match
```
{{< /tab >}}
{{< /tabs >}}
## SonarQube returns empty results
Issue: SonarQube analysis returns no projects or issues.
Solution:
1. Verify your SonarCloud organization key is correct.
2. Ensure you have at least one project configured in SonarCloud.
3. Check that your SonarQube token has the necessary permissions.
4. Confirm your project has been analyzed at least once in SonarCloud.

File diff suppressed because it is too large Load Diff

View File

@@ -134,14 +134,17 @@
"Specific-version",
"Svelte",
"Testcontainers-Cloud",
"TypeScript",
"Ubuntu",
"Ubuntu/Debian",
"Unix-pipe",
"Updated-Dockerfile",
"Use-Docker-Init",
"Use-OpenAI",
"Using-Docker-Hardened-Images",
"Using-the-CLI",
"Using-the-GUI",
"Using-the-official-image",
"VS-Code",
"Vue",
"WSL-2-backend-Arm-Early-Access",