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

> Learn how the Corsair project efficiently tracks issues using GitHub templates, branch naming, and automated linking from claim to merge for seamless integration management.

- Repository: [corsairdev/corsair](https://github.com/corsairdev/corsair)
- Tags: how-to-guide
- Published: 2026-09-01

---

**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)](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)](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`](https://github.com/corsairdev/corsair/blob/main/CONTRIBUTING.md) lines 60-70](https://github.com/corsairdev/corsair/blob/main/CONTRIBUTING.md#L60-L70):

```bash
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/PLUGIN_PR_RULES.md)](https://github.com/corsairdev/corsair/blob/main/.github/PLUGIN_PR_RULES.md#L28-L34) enforces this requirement:

```markdown

## 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`](https://github.com/corsairdev/corsair/blob/main/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`](https://github.com/corsairdev/corsair/blob/main/.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:

```markdown
- [ ] 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`](https://github.com/corsairdev/corsair/blob/main/CONTRIBUTING.md)** – Complete workflow documentation from claim to merge
- **[`README.md`](https://github.com/corsairdev/corsair/blob/main/README.md)** – Entry point with integration claim instructions
- **[`.github/PLUGIN_PR_RULES.md`](https://github.com/corsairdev/corsair/blob/main/.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`](https://github.com/corsairdev/corsair/blob/main/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)](https://github.com/corsairdev/corsair/blob/main/README.md#L35) and [[`CONTRIBUTING.md`](https://github.com/corsairdev/corsair/blob/main/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/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.