How to Use the GitHub Issue Tracking System in the Corsair Open-Source Project

The Corsair repository uses a structured GitHub-based workflow with enforced templates, branch naming conventions, and automated issue linking to track integrations from claim to merge.

This guide explains exactly how issues are tracked in the corsairdev/corsair open-source project. The workflow is designed to prevent duplicate work, maintain audit trails, and keep third-party API integrations aligned with the project roadmap.

The 7-Step Issue Tracking Workflow

1. Claim an Integration via the OSS Portal

Before opening any code changes, developers must first check the public OSS Integrations page at https://corsair.dev/oss. This page shows which APIs are available for contribution. Claiming an integration reserves the work and prevents multiple contributors from overlapping efforts.

As documented in the [README.md](https://github.com/corsairdev/corsair/blob/main/README.md#L35), this claim step is mandatory for all new integration work.

2. Open a GitHub Issue with Required Details

After claiming, contributors create a new GitHub issue that serves as the single source of truth for the work. The issue must include:

• API name and documentation links
• Required endpoints
• Authentication model (OAuth 2.0, API key, etc.)
• Webhook requirements (if any)

The [CONTRIBUTING.md](https://github.com/corsairdev/corsair/blob/main/CONTRIBUTING.md#L7-L15) specifies that no work should begin without this issue in place.

3. Use the Structured Issue Templates

The repository provides standardized templates located in .github/ISSUE_TEMPLATE/. Contributors must select the correct template:

• Bug report – for defects and unexpected behavior
• Feature request – for core platform enhancements
• Integration request – for new third-party API connectors

These templates enforce consistent information collection, making issues searchable and reviewable.

4. Create Branches with Issue Number References

Branch naming follows a strict convention that embeds the issue number. From [CONTRIBUTING.md lines 60-70](https://github.com/corsairdev/corsair/blob/main/CONTRIBUTING.md#L60-L70):

git checkout -b feat/slack-integration-#123

This naming pattern creates an immediate, unambiguous link between code changes and their originating issue.

5. Link Issues in Pull Requests with Closing Keywords

Every PR must reference its issue using GitHub's closing keywords. The [PLUGIN_PR_RULES.md](https://github.com/corsairdev/corsair/blob/main/.github/PLUGIN_PR_RULES.md#L28-L34) enforces this requirement:

## Description

Implemented Slack conversation listing and message posting.

## Fixes

Fixes #123

Valid keywords include Fixes, Closes, or Resolves. When the PR merges, GitHub automatically closes the linked issue.

6. Include Demo Evidence for Integration PRs

Because CI systems cannot call live third-party APIs, Corsair requires manual verification. Per [PLUGIN_PR_RULES.md lines 35-40](https://github.com/corsairdev/corsair/blob/main/.github/PLUGIN_PR_RULES.md#L35-L40), PRs must include:

• A short demo video or screenshots showing the integration working
• Evidence that the implementation matches the issue description

Reviewers verify alignment between the issue specification and the delivered code.

7. Maintain Post-Merge Discussion in Issue Threads

After merge, the issue closes automatically. However, the issue thread remains the authoritative historical record for:

• Bug reports discovered after release
• Enhancement requests
• Usage questions specific to that integration

This creates a complete audit trail from initial claim through ongoing maintenance.

Enforcing Issue Tracking Compliance

The Corsair project combines human guidelines and automated checks to maintain workflow discipline:

Enforcement Layer	Mechanism	Location
Human review	Mandatory checklist in PR template	.github/PULL_REQUEST_TEMPLATE.md
Automated validation	Greptile rules scan for issue links	CI pipeline configuration
Native GitHub behavior	Issue auto-close on merge	GitHub platform

The PR template explicitly requires contributors to confirm:

- [ ] Linked issue (e.g. "Fixes #123")
- [ ] Demo video showing the integration in action

Key Configuration Files for Issue Tracking

Understanding these source files gives you full visibility into how Corsair manages work items:

• CONTRIBUTING.md – Complete workflow documentation from claim to merge
• README.md – Entry point with integration claim instructions
• .github/PLUGIN_PR_RULES.md – Hard requirements for integration PRs including issue linking and demos
• .github/ISSUE_TEMPLATE/ – Structured templates for bugs, features, and integration requests

Summary

• Claim first: Check corsair.dev/oss before any code work to reserve your integration
• Issue as source of truth: Every change begins with a GitHub issue using the correct template
• Traceable branches: Name branches with issue numbers (feat/name-#123) for automatic linkage
• Mandatory PR linking: Use Fixes #123 to enable auto-close and satisfy PLUGIN_PR_RULES.md requirements
• Demo requirement: Integration PRs need video/screenshot evidence since third-party APIs cannot be CI-tested
• Complete audit trail: The system creates searchable records from idea through ongoing maintenance

Frequently Asked Questions

What happens if I skip the integration claim step?

The Corsair maintainers will likely close your PR. The [README.md](https://github.com/corsairdev/corsair/blob/main/README.md#L35) and [CONTRIBUTING.md](https://github.com/corsairdev/corsair/blob/main/CONTRIBUTING.md#L7-L15) require claiming via corsair.dev/oss to prevent duplicate work and ensure the project roadmap stays coordinated.

Can I work on an issue someone else already claimed?

No. The OSS portal shows real-time claim status. If an integration appears claimed, select a different API or contact the maintainers in the existing issue thread to offer collaboration.

Why does Corsair require demo videos instead of automated tests?

Third-party APIs require live credentials and external network access that CI environments cannot reliably provide. The [PLUGIN_PR_RULES.md](https://github.com/corsairdev/corsair/blob/main/.github/PLUGIN_PR_RULES.md#L35-L40) mandates visual demos as pragmatic proof that integrations function against real endpoints.

How do I find closed issues for a specific integration?

Search GitHub issues with the integration name and is:closed filter. The branch naming convention (feat/integration-#123) and Fixes references in merged PRs make historical discovery straightforward.

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