Link to External GitLab Issues

PPM work items can reference issues in external systems such as GitLab using the external_ref and external_url fields. This is useful for cross-repo tracking when the actual code work happens in a separate GitLab project.

Fields for external linking

Field	Type	Description
external_ref	varchar(512)	A short reference identifier (e.g. raytio/backend#142)
external_url	varchar(1024)	The full URL to the external issue

Both fields are optional and independent — you can set one or both.

Link an external issue when creating a work item

POST /rest/v1/t_ppm_work_items

{
  "project_id": "a1b2c3d4-...",
  "work_item_type": "ISSUE",
  "work_item_name": "Add PPM API endpoints",
  "external_ref": "raytio/backend#142",
  "external_url": "https://gitlab.com/raytio/backend/-/issues/142"
}

Add an external link to an existing work item

PATCH /rest/v1/t_ppm_work_items?id=eq.<work-item-id>

{
  "external_ref": "raytio/frontend#87",
  "external_url": "https://gitlab.com/raytio/frontend/-/issues/87"
}

Remove an external link

Set the fields to null:

PATCH /rest/v1/t_ppm_work_items?id=eq.<work-item-id>

{
  "external_ref": null,
  "external_url": null
}

Find work items linked to an external reference

The external_ref field is indexed, so you can query it efficiently:

GET /rest/v1/t_ppm_work_items?external_ref=eq.raytio/backend%23142

note

URL-encode the # character as %23 when passing it as a query parameter.

Suggested conventions

To keep external references consistent across your team, consider these patterns:

Pattern	Example	When to use
group/project#number	raytio/backend#142	GitLab issues
group/project!number	raytio/backend!58	GitLab merge requests
JIRA-KEY	PROJ-1234	Jira tickets

The external_ref field is free-form text, so you can adopt any convention that suits your workflow.