Filing GitHub Issues for CockroachDB
File issues on cockroachdb/cockroach using the repo's issue templates and
CockroachDB labeling conventions.
Workflow
Step 1: Discover Issue Templates
The repo has issue templates in .github/ISSUE_TEMPLATE/. Blank issues are
disabled, so one of these templates must be used:
- bug_report.md — Reproducible bugs
- feature_request.md — New functionality proposals
- performance-inquiry.md — Performance problems
For investigation issues (tracking research/analysis work that doesn't fit the above), use the investigation structure in the Investigation section below instead of a template.
If the issue type is obvious from context (e.g., the user described a bug), pick the matching template without asking. Only ask when ambiguous.
Read the chosen template file to get its structure and required sections.
Step 2: Gather Information
If the user has already provided context (e.g., they described a bug before invoking this skill), use that context to pre-fill sections and confirm rather than re-asking.
Otherwise, ask the user for:
- Issue type — Which template fits best
- Title — Concise, prefixed with the affected package (e.g.,
sql/schemachanger: ...) - Body content — Walk through template sections conversationally
Step 3: Discover Available Labels
Query the repo's labels to find the appropriate team and areas for the issue if they aren't already known:
# Search for labels by prefix (T-, A-).
gh label list -R cockroachdb/cockroach --search "<prefix>" --limit 100
Use the label conventions table below to guide which prefixes to search. Match labels to the issue's team and areas. Do not invent labels — only use ones that exist in the repo.
Step 4: Compose and Confirm
Assemble the full issue using the template structure. Show the user a preview of the complete issue (title, labels, and body) and get explicit confirmation before filing.
Step 5: File the Issue
gh issue create -R cockroachdb/cockroach \
--title "<title>" \
--label "<labels>" \
--body "$(cat <<'EOF'
<assembled issue body>
EOF
)"
Display the issue URL after filing.
Investigation Issues
For research/analysis work, don't use a bug report template. Instead, file directly with this structure:
**Summary:**
Brief description of what needs investigation.
**Findings:**
- Finding 1
- Finding 2
**Code References:**
- [file.go:123](https://github.com/cockroachdb/cockroach/blob/master/pkg/path/file.go#L123)
**Next Steps:**
- [ ] Action item 1
- [ ] Action item 2
Use C-investigation as the category label. Do not include bug-report
sections like "Steps to reproduce" or "Expected behavior" — they don't
apply to investigations.
Label Conventions
| Prefix | Purpose | Examples |
|--------|---------|----------|
| T- | Team owner | T-sql-foundations, T-kv, T-storage, T-obs |
| A- | Technical area | A-sql-optimizer, A-sql-execution, A-kv-replication, A-spanconfig |
| O- | Origin/discovery | O-roachtest, O-support, O-community |
| C- | Category/type | C-bug, C-enhancement, C-investigation, C-test-failure |
Always include the O-agent label to indicate the issue was filed via this
skill. Apply additional labels from the template frontmatter plus any
relevant T-, A-, O-, and C- labels. Ask the user if they want
additional labels. Do not assign anyone unless the user explicitly says
who to assign.
Jira Epic Association
If the issue should be associated with a Jira epic, add a line at the very bottom of the issue body:
Epic CRDB-12358
This causes the Jira issue (created automatically by automation) to be associated with that epic. Ask the user if there's a relevant epic to link.
Best Practices
- Code references: Use GitHub URLs with line numbers:
[file.go:123](https://github.com/cockroachdb/cockroach/blob/master/pkg/path/file.go#L123) - Stable references: Include commit SHA in URLs when line numbers may shift.
- Correlation evidence: Include timestamped logs for performance issues. Paste excerpts inline.
- Content: Use markdown. Be specific about versions, configs, environments. Include repro steps.
- No release notes in GitHub issues (release notes are only for PRs and commits).
- No Jira footer: Do not add a "Jira issue: CRDB-XXXXX" line. Jira linking is handled automatically by automation after the issue is created.
- Confirm before filing: Always show the complete issue and get explicit approval before running
gh issue create.