Monorepo Cross-Package Issue Template

Monorepo Cross-Package Issue Template

Monorepos present unique challenges for issue management: a bug might affect multiple packages, require multiple team owners, and have different severity levels across packages. This template addresses those complexities.

Template Structure

name: "Bug Report (Monorepo)"
description: "Report an issue affecting one or more packages"
title: "[Bug]: "
labels: ["bug", "triage"]
body:
  - type: checkboxes
    id: affected_packages
    attributes:
      label: "Affected Packages"
      description: "Select all packages affected by this issue"
      options:
        - label: "@org/core"
        - label: "@org/ui"
        - label: "@org/api-client"
        - label: "@org/cli"
        - label: "@org/config"
        - label: "@org/utils"
    validations:
      required: true
  - type: dropdown
    id: cross_dependency
    attributes:
      label: "Cross-Package Impact"
      description: "Does this issue involve interactions between packages?"
      options:
        - "Single package only"
        - "Multiple packages affected independently"
        - "Issue is in dependency chain between packages"
    validations:
      required: true
  - type: textarea
    id: description
    attributes:
      label: "Issue Description"
    validations:
      required: true
  - type: textarea
    id: reproduction
    attributes:
      label: "Reproduction Steps"
      description: "Include which package commands to run"
      placeholder: |
        1. cd packages/core
        2. npm run test
        3. See failure in...
    validations:
      required: true
  - type: input
    id: package_versions
    attributes:
      label: "Package Versions"
      description: "Run 'npx lerna list --json' or equivalent"
      placeholder: "@org/core@1.2.3, @org/ui@2.0.1"
    validations:
      required: true

Package Routing with GitHub Actions

Combine this template with a GitHub Actions workflow that reads the checked packages and automatically applies package-specific labels:

# .github/workflows/label-packages.yml
on:
  issues:
    types: [opened]

Cross-Dependency Impact

The cross-dependency dropdown helps maintainers understand whether the fix is isolated to one package or requires coordinated changes across multiple packages. This affects release planning and testing strategy.

Version Reporting

In monorepos, version information for all affected packages is crucial. The package versions field helps determine whether the issue exists in the latest versions or only in specific combinations.