Amber Issue-to-PR Automation

Overview

Amber is a background agent that automatically handles GitHub issues and creates pull requests. This system allows team members to trigger automated fixes, refactoring, and test additions without requiring direct access to Claude Code.

How It Works

graph LR
    A[Create Issue] --> B[Add Label]
    B --> C[GHA Triggers]
    C --> D[Amber Executes]
    D --> E[Create PR]
    E --> F[Review & Merge]

Create Issue: Team member creates an issue using one of the Amber templates
Add Label: Apply appropriate label (amber:auto-fix, amber:refactor, amber:test-coverage)
GHA Triggers: GitHub Actions workflow detects label and starts Amber
Amber Executes: Amber analyzes the issue and makes changes
Create PR: Amber creates a pull request with the changes
Review & Merge: Team reviews and merges the PR

Available Workflows

🤖 Auto-Fix (Low Risk)

Trigger Label: amber:auto-fix

Use For:

Code formatting (gofmt, black, prettier)
Linting violations
Unused import removal
Documentation formatting

Template: .github/ISSUE_TEMPLATE/amber-auto-fix.yml

Example:

Title: [Amber] Fix frontend linting errors
Label: amber:auto-fix
Body:
  Issue: Frontend code fails eslint checks
  Files: components/frontend/src/**/*.tsx
  Fix Type: Linting Violations

Expected Outcome: PR with automated formatting/linting fixes, all tests pass

🔧 Refactoring (Medium Risk)

Trigger Label: amber:refactor

Use For:

Breaking large files into modules
Extracting repeated patterns
Replacing context.TODO() with proper context
Improving error handling

Template: .github/ISSUE_TEMPLATE/amber-refactor.yml

Example:

Title: [Amber Refactor] Break sessions.go into modules
Label: amber:refactor
Body:
  Current State: handlers/sessions.go is 3,495 lines
  Desired State: Break into lifecycle.go, status.go, jobs.go, validation.go
  Constraints: Maintain backward compatibility, all tests pass
  Priority: P0

Expected Outcome: PR with refactored code, detailed migration notes, all tests pass

🧪 Test Coverage (Medium Risk)

Trigger Label: amber:test-coverage

Use For:

Adding missing unit tests
Contract tests for API endpoints
Edge case coverage
Improving test coverage percentage

Template: .github/ISSUE_TEMPLATE/amber-test-coverage.yml

Example:

Title: [Amber Tests] Add contract tests for sessions API
Label: amber:test-coverage
Body:
  Untested Code: components/backend/handlers/sessions.go
  Test Type: Contract Tests (API endpoints)
  Test Scenarios:
    - Happy path: create session with valid spec
    - Error: missing API key
    - Edge case: very long prompt
  Target Coverage: 60%

Expected Outcome: PR with new tests following project conventions (table-driven for Go)

Advanced Usage

Manual Trigger via Comment

You can trigger Amber by commenting on an existing issue using either:

/amber execute

Or simply mention Amber:

@amber

Both commands tell Amber to execute the proposal described in the issue body. Amber will read the full issue context and determine the appropriate action.

Use Cases:

After discussing a refactoring approach in an issue, comment @amber to have Amber implement it
Quick fixes without needing to add labels: @amber please fix the linting errors in this file
Code review requests: @amber review this approach and suggest improvements

Issue Format Requirements

For Amber to work effectively, structure your issue body like this:

## Problem
[Describe what needs to be fixed]

## Files
File: `path/to/file.go`
File: `path/to/another.py`

## Instructions
[Step-by-step instructions for Amber]

## Success Criteria
- [ ] All linters pass
- [ ] All tests pass
- [ ] Follows CLAUDE.md standards

Key Fields:

File: or Path: - Amber extracts file paths automatically
Instructions: or Task: - Main instructions section
Success criteria checklist

Configuration

Amber's behavior is controlled by:

Workflow: .github/workflows/amber-issue-handler.yml
Config: .claude/amber-config.yml (automation policies)
Project Standards: CLAUDE.md (Amber follows all project conventions)

Risk Levels

Amber classifies changes by risk:

Risk	Actions	Auto-Merge	Examples
Low	Auto-fix, create PR	No (requires review)	Formatting, linting
Medium	Create PR with proposal	No	Refactoring, test additions
High	Report only, no PR	N/A	Breaking changes, security issues

Security

The workflow follows strict security practices:

No Command Injection: All user input (issue titles, bodies) passed via environment variables
Token Scoping: GITHUB_TOKEN has minimal permissions (contents:write, issues:write, pull-requests:write)
Anthropic API Key: Stored as GitHub secret (ANTHROPIC_API_KEY)
Branch Protection: Never pushes to main, always creates feature branches

Reference: GitHub Actions Security Guide

Monitoring

View Workflow Runs

# Via GitHub CLI
gh run list --workflow=amber-issue-handler.yml

# Watch specific run
gh run watch <run-id>

# View logs
gh run view <run-id> --log

Amber-Generated PRs

All PRs created by Amber have:

Title: [Amber] Fix: <issue title>
Labels: amber-generated, auto-fix, <action-type>
Body: Detailed summary with links back to original issue

Troubleshooting

Amber Workflow Didn't Trigger

Possible Causes:

Wrong label applied (must be exact: amber:auto-fix, not amber auto-fix)
Issue not in correct repository
ANTHROPIC_API_KEY secret not configured

Debug:

gh run list --workflow=amber-issue-handler.yml --limit 5

Amber Created PR but Tests Failed

Expected Behavior: Amber runs linters/tests before committing, but CI may have additional checks.

Actions:

Review PR, identify failing test
Add comment to PR: /amber fix-tests
Amber will update the PR with fixes

Alternative: Close PR, update original issue with additional context, re-trigger Amber

Amber Encountered Error

Amber will comment on the issue with error details:

⚠️ Amber encountered an error while processing this issue.

**Action Type:** refactor
**Workflow Run:** [link to logs]

Please review the workflow logs for details.

Common Issues:

Issue description lacks sufficient context
Specified files don't exist
Changes too complex for automation (requires manual intervention)

Best Practices

✅ Good Issue Examples

Auto-Fix:

Title: [Amber] Fix Go formatting in backend handlers
Label: amber:auto-fix

## Problem
Backend handlers fail gofmt checks after recent commits.

## Files
File: `components/backend/handlers/*.go`

## Fix Type
Code Formatting

Refactoring:

Title: [Amber Refactor] Extract git operations from sessions.go
Label: amber:refactor

## Current State
File: `components/backend/handlers/sessions.go` (line 1200-1800)
Issue: Git operations mixed with session handling logic

## Desired State
Create new file: `components/backend/git/session_operations.go`
Move git clone, fork, PR creation functions

## Constraints
- Maintain current API (no breaking changes)
- Add unit tests for extracted functions
- All existing tests must pass

Test Coverage:

Title: [Amber Tests] Add contract tests for Projects API
Label: amber:test-coverage

## Untested Code
File: `components/backend/handlers/projects.go`
Functions: CreateProject, DeleteProject, ListProjects

## Test Scenarios
- Happy path: create project with valid name
- Error: create project with duplicate name
- Error: create project with invalid characters
- Edge: list projects when none exist

## Target Coverage
60% for projects.go

❌ Avoid These Patterns

Too Vague:

Title: Fix stuff
Label: amber:auto-fix

Make the code better.

Issue: No specific files, instructions, or success criteria

Too Broad:

Title: Refactor entire backend
Label: amber:refactor

Rewrite all backend code to be perfect.

Issue: Scope too large, no clear boundaries

Security Risk:

Title: Update API keys in code
Label: amber:auto-fix

Hardcode new API keys in handlers.

Issue: Amber will refuse (security violation)

Extending Amber

Adding New Workflow Types

Update workflow (.github/workflows/amber-issue-handler.yml):

if: |
  github.event.label.name == 'amber:your-new-type'

Create issue template (.github/ISSUE_TEMPLATE/amber-your-type.yml)

Update config (.claude/amber-config.yml):

automation_policies:
  your_new_type:
    enabled: true
    categories:
      - name: "Your New Type"
        patterns: ["pattern1", "pattern2"]

Document in this file

Metrics & Reporting

Track Amber's effectiveness:

# Count Amber-generated PRs
gh pr list --label amber-generated --state all

# Amber success rate (merged vs. closed)
gh pr list --label amber-generated --state merged | wc -l
gh pr list --label amber-generated --state closed | wc -l

# Average time from issue creation to PR merge
# (requires custom script or GitHub API)

Goal: 90% of Amber PRs merged without modification

FAQ

Q: Can Amber handle multiple files in one PR? A: Yes, specify multiple files in the issue body. Amber will modify all relevant files.

Q: Can I trigger Amber without an issue? A: No, issues provide context and audit trail. For ad-hoc tasks, create a temporary issue.

Q: What happens if Amber's PR conflicts with other work? A: Standard git conflict resolution. Review the PR, resolve conflicts manually, or close and re-trigger after merging other work.

Q: Can Amber create breaking changes? A: No, Amber is configured to reject breaking changes. It will comment on the issue if it detects a breaking change request.

Q: How much does Amber cost (API usage)? A: Depends on task complexity. Typical auto-fix: ~10K tokens ($0.03), refactoring: ~50K tokens ($0.15), test coverage: ~30K tokens ($0.09). Monitor via Anthropic dashboard.

Support

Issues with Amber automation:

Check workflow logs: gh run view --log
Review issue format requirements (above)
Create issue with label amber:help for manual review

Feature Requests: Create issue titled [Amber Feature Request] ... describing desired capability.

Last Updated: 2025-11-21 Maintained By: Platform Team

Navigation Menu

Amber Issue-to-PR Automation

Overview

How It Works

Available Workflows

🤖 Auto-Fix (Low Risk)

🔧 Refactoring (Medium Risk)

🧪 Test Coverage (Medium Risk)

Advanced Usage

Manual Trigger via Comment

Issue Format Requirements

Configuration

Risk Levels

Security

Monitoring

View Workflow Runs

Amber-Generated PRs

Troubleshooting

Amber Workflow Didn't Trigger

Amber Created PR but Tests Failed

Amber Encountered Error

Best Practices

✅ Good Issue Examples

❌ Avoid These Patterns

Extending Amber

Adding New Workflow Types

Metrics & Reporting

FAQ

Related Documentation

Support

FilesExpand file tree

amber-automation.md

Latest commit

History

amber-automation.md

File metadata and controls

Amber Issue-to-PR Automation

Overview

How It Works

Available Workflows

🤖 Auto-Fix (Low Risk)

🔧 Refactoring (Medium Risk)

🧪 Test Coverage (Medium Risk)

Advanced Usage

Manual Trigger via Comment

Issue Format Requirements

Configuration

Risk Levels

Security

Monitoring

View Workflow Runs

Amber-Generated PRs

Troubleshooting

Amber Workflow Didn't Trigger

Amber Created PR but Tests Failed

Amber Encountered Error

Best Practices

✅ Good Issue Examples

❌ Avoid These Patterns

Extending Amber

Adding New Workflow Types

Metrics & Reporting

FAQ

Related Documentation

Support