An Issue Link connects a Catalio Requirement or Application to an issue in an external issue tracker — GitHub, Linear, Jira, or Azure DevOps. Issue Links close the traceability gap between the specification layer (Catalio) and the delivery layer (your issue tracker), answering the questions: “Has this requirement been implemented?” and “Which requirements does this issue address?”
Issue Links can also be added to an Initiative’s scope as first-class scope items, letting you track which external delivery work is part of an Initiative’s scope — alongside requirements, components, and other scoped entities.
Supported Platforms
| Platform | Notes |
|---|---|
| GitHub | GitHub Issues — connected integration with automatic metadata sync |
| Linear | Linear issue tracking — connected integration with automatic metadata sync |
| Azure DevOps | Azure DevOps Work Items — connected integration with automatic metadata sync |
| Jira | Atlassian Jira (Cloud and Data Center) — manual linking only, no live sync yet |
Note
Until the Azure DevOps integration is enabled for your organization, Azure DevOps links behave like Jira’s below.
For Jira, platform is a valid value for manual metadata entry, but there is no connected account
and sync_cached_data cannot refresh its cached fields automatically.
Link Types
| Link Type | When It Applies |
|---|---|
| created_from | The issue was created directly from this Requirement in Catalio |
| linked_manually | An existing issue was manually linked to this Requirement after the fact |
| pull_request | Link created from or to a GitHub pull request |
created_from links are created automatically when you use Catalio’s “Create Issue” action. linked_manually links are created when you paste an existing issue URL or ID into the link dialog. pull_request links connect a GitHub pull request rather than an issue.
Linking to Requirements vs. Applications
Issue Links can be scoped to either a Requirement or an Application:
- Requirement link — The most common case. One issue implements one requirement. Required for per-requirement traceability reports.
- Application link — Link an issue directly to an Application without associating it to a specific requirement. Useful for infrastructure, DevOps, or platform-wide issues that don’t map to a single requirement.
At least one of requirement_id or application_id must be set on every link.
Cached Metadata
Catalio caches issue metadata locally for offline display and reporting:
- title — Issue title at time of last sync
- status — Issue state (open, in progress, closed, etc.)
- assignee — Assigned team member
This cached data allows Catalio to show issue context without a live API call. For GitHub, Linear, and Azure DevOps links, use the sync_cached_data action to refresh metadata from the platform when you want the latest status. Jira links must be updated manually since there is no connected sync source for that platform yet.
Soft Deletion
Issue Links use soft delete (archival). When you delete a link, it is marked with an archived_at timestamp and hidden from all views — but the link record is retained for audit purposes. The unique constraint that prevents duplicate links applies only to non-archived records.
Key Fields
| Field | Purpose |
|---|---|
| platform | Which issue tracker: github, linear, jira, or azure_devops |
| external_issue_id | Numeric or string identifier from the external platform |
| external_identifier | Full identifier for display (e.g., “GH-123”, “LIN-456”, “PROJ-789”) |
| link_type | created_from, linked_manually, or pull_request |
| requirement_id | The linked Requirement (nullable; one of requirement_id or application_id required) |
| application_id | The linked Application (nullable; alternative to requirement_id) |
| cached_title | Cached issue title from last sync |
| cached_status | Cached issue status from last sync |
| cached_assignee | Cached assignee from last sync |
Uniqueness
Catalio enforces that each external issue is linked to a given Requirement (or Application) at most once. Duplicate links — where the same issue is linked to the same Requirement twice — are prevented at the database level. Archived links are excluded from this uniqueness check, so if you delete a link and recreate it, the new link is valid.
Traceability Reporting
Issue Links are the foundation of Catalio’s traceability matrix:
- Requirement coverage — Which requirements have at least one linked issue? Which are unimplemented?
- Implementation status — For requirements with linked issues, what is the combined issue status?
- Cross-platform view — One requirement can link to issues across multiple platforms simultaneously
This makes it possible to answer “Is requirement X delivered?” by checking whether linked issues are closed — without leaving Catalio.
Relationships at a Glance
| Related Concept | Relationship |
|---|---|
| Requirements | Issue Links connect Requirements to external delivery work |
| Applications | Issue Links can scope directly to an Application |
| Initiatives | Issue Links can be added to an Initiative’s scope as scope items |
| Repositories | Repositories are the code layer; Issue Links are the work-item layer |
Best Practices
Create links at requirement approval, not at implementation.
The moment a requirement is approved and a corresponding issue is created in your tracker, link them. Waiting until after implementation means traceability gaps form and are hard to backfill.
Link issues to the most specific requirement possible.
Linking an issue to a broad feature requirement (e.g., “Invoice Processing”) when it implements a specific requirement (“Invoice PDF export must preserve line-item totals”) produces misleading traceability reports. Prefer specificity.
Sync cached data regularly.
For GitHub, Linear, and Azure DevOps links, issue status in Catalio reflects the last sync, not the current platform state. For sprint reviews or status reports, trigger a sync first to ensure the displayed status is current. Jira links have no sync source, so keep their cached status current by editing the link manually.
Use application-level links for cross-cutting work.
Not every issue maps to a single requirement. DevOps automation, performance tuning, and infrastructure upgrades often span many requirements. Link these to the Application directly, rather than forcing an incorrect requirement link.
Next Steps
- Understand Requirements — Learn what Issue Links are tracing
- Connect Repositories — Establish code-level traceability alongside issue links
- Work with Applications — See how applications anchor both code and work-item traceability
Pro Tip: After an initial batch of requirement approvals, use Catalio’s requirement list view with the “linked issues” filter set to “none” to identify which requirements are still unlinked. This surfaces gaps before sprint planning, not after implementation.
Support
- Documentation: Continue reading about Requirements and Repositories
- In-App Help: The AI assistant can help identify requirements without linked issues
- Email: support@catalio.ai
- Community: Share traceability patterns with other Catalio users
