failure-cause

Analyze CI failures for any commit, branch, or pull request. This command intelligently detects the context and provides detailed failure analysis.

Usage

autoci failure-cause [URL] [flags]

Examples

Analyze a Pull Request

# Using a GitHub URL
autoci failure-cause https://github.com/owner/repo/pull/123
 
# Using flags
autoci failure-cause --repo owner/repo --pr 123

Analyze a Branch

# Using a GitHub URL
autoci failure-cause https://github.com/owner/repo/tree/main
 
# Using flags (analyzes latest commit on branch)
autoci failure-cause --repo owner/repo --branch main

Analyze a Specific Commit

# Using a GitHub URL
autoci failure-cause https://github.com/owner/repo/commit/abc123
 
# Using flags
autoci failure-cause --repo owner/repo --commit abc123

Analyze a GitHub Actions Run

# Direct Actions run URL
autoci failure-cause https://github.com/owner/repo/actions/runs/123456
 
# Using flags
autoci failure-cause --repo owner/repo --run 123456

Interactive Mode

Browse recent CI runs and select one to analyze:

autoci failure-cause --repo owner/repo --interactive

Auto-detect from Current Repository

When run from within a git repository, AutoCI can auto-detect the repository and current branch:

# Analyzes the current branch's latest commit
autoci failure-cause

Scheduled Workflows

View and analyze failed scheduled workflows:

autoci failure-cause --repo owner/repo --scheduled

Flags

How It Works

The failure-cause command uses a cascading detection strategy to find and analyze CI failures:

1. GitHub Actions: If the repository uses GitHub Actions, AutoCI fetches detailed logs and can pinpoint exact error lines
2. Commit Status API: For systems like Prow (Kubernetes), Jenkins, or older CI integrations
3. Checks API: For modern CI systems like CircleCI 2.0+, BuildKite, and Azure Pipelines

The command automatically detects which CI system is in use and adapts its analysis accordingly.

Requirements

• GitHub Token: Set the GITHUB_TOKEN environment variable with appropriate scopes:
  • repo scope for private repositories
  • public_repo scope for public repositories
  • workflow scope for GitHub Actions access

Output

The command provides:

• Clear identification of which CI jobs/workflows failed
• Root cause analysis powered by AI
• Specific error messages and stack traces
• Direct links to full logs when available

CI System Support

AutoCI supports multiple CI systems with varying levels of detail:

Tips

• For the best analysis, ensure your GitHub token has the necessary permissions
• Use --verbose flag for more detailed output during analysis
• The command works with both public and private repositories (with appropriate permissions)
• When analyzing non-PR commits, the command uses -1 as the PR number internally for API compatibility