How to Report a Bug in Apple container: A Step-by-Step Guide

To report a bug in apple/container, gather environment details using sw_vers, xcodebuild -version, and container --version, then submit a structured issue using the GitHub bug template at .github/ISSUE_TEMPLATE/01-bug.yml.

The apple/container repository provides a dedicated framework for managing containers on macOS. When you encounter unexpected behavior, following the official bug reporting protocol ensures maintainers can reproduce and resolve issues efficiently. This guide walks you through the complete process to report a bug in apple/container, from gathering system information to submitting a structured issue.

Prerequisites for Reporting Bugs

Before opening an issue, collect the essential diagnostic data specified in docs/bug-report-how-to.md. The guide requires three categories of information: reproduction steps, problem description, and environment details.

Capture Environment Information

Run the following commands to record your system state:

# Record macOS version

sw_vers

# Record Xcode version

xcodebuild -version

# Record container CLI version

container --version

Collect Debug Logs

Capture verbose output using the --debug flag or retrieve logs from existing containers:

# Run with debug output

container --debug create --name test-app ubuntu:latest

# Capture logs from a running container

container logs test-app > test-app.log

How to Submit the Bug Report

The repository uses a structured template located at .github/ISSUE_TEMPLATE/01-bug.yml to standardize bug reports.

1. Navigate to the Issues tab of the apple/container repository.
2. Click New issue and select the Bug report template.
3. Fill in the required fields with your gathered data.

Formatting Your Report

When describing reproduction steps, use fenced code blocks for commands:

**Steps to reproduce**
1. `container --debug create --name test-app ubuntu:latest`
2. `container start test-app`

**Actual behavior**

failed to bootstrap container test-app

**Expected behavior**
Container starts and prints its ID.

**Logs**

```bash

# paste relevant portion of test-app.log here

## Key Documentation References

According to the apple/container source code, these files define the reporting standards:

- **[`docs/bug-report-how-to.md`](https://github.com/apple/container/blob/main/docs/bug-report-how-to.md)**: The complete guide for preparing effective bug reports, including environment checks and log collection strategies.
- **[`.github/ISSUE_TEMPLATE/01-bug.yml`](https://github.com/apple/container/blob/main/.github/ISSUE_TEMPLATE/01-bug.yml)**: The GitHub issue template that structures bug reports with required fields.
- **[`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md)**: Documentation for CLI commands such as `container --debug` and `container logs`.

## Summary

- **Gather environment data** using `sw_vers`, `xcodebuild -version`, and `container --version` before reporting.
- **Use debug flags** (`--debug`) and `container logs` to capture verbose output that helps diagnose failures.
- **Follow the template** in [`.github/ISSUE_TEMPLATE/01-bug.yml`](https://github.com/apple/container/blob/main/.github/ISSUE_TEMPLATE/01-bug.yml) to ensure your report includes reproduction steps, expected behavior, and actual behavior.
- **Reference the guide** at [`docs/bug-report-how-to.md`](https://github.com/apple/container/blob/main/docs/bug-report-how-to.md) for detailed preparation instructions.

## Frequently Asked Questions

### Where is the official bug reporting guide for apple/container?

The official guide lives in the repository at [`docs/bug-report-how-to.md`](https://github.com/apple/container/blob/main/docs/bug-report-how-to.md). This file explains how to collect environment information, capture logs, and structure your report for the fastest resolution.

### What debug flags should I use when reporting a bug?

Use the `--debug` flag with any `container` command to generate verbose output, as documented in [`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md). For example, run `container --debug create --name test ubuntu:latest` to see detailed bootstrap information.

### How do I find the container CLI version?

Run `container --version` in your terminal. Include this output in your bug report along with the macOS version (`sw_vers`) and Xcode version (`xcodebuild -version`) to provide complete environment context.

### What if the bug report template doesn't load automatically?

If the template at [`.github/ISSUE_TEMPLATE/01-bug.yml`](https://github.com/apple/container/blob/main/.github/ISSUE_TEMPLATE/01-bug.yml) doesn't appear, navigate to the file directly in the repository and manually copy the structure into your new issue, ensuring you include sections for reproduction steps, expected behavior, actual behavior, and environment details.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}