Ticket Sync

Ticket Sync imports external issues or work items into a workspace as Polygent tickets and, for Azure DevOps/TFS, reports ticket stage changes back to the work item.

Supported integrations

Each workspace uses one ticket source, configured on its Tickets tab (requires Edit Workspaces).

Integration	Supported behavior
GitHub	Import issues, create issues, filter by labels, auto-cancel on close, and create and track pull requests.
Azure DevOps / TFS	Import work items of any type, create Bugs, filter by area path and tags, sync stages back to work-item states, auto-cancel on close, and create and track pull requests.

The workspace ticket source is also the integration used to create pull requests; with Source set to None, pull-request creation fails. Use a dedicated least-privilege token.

How synchronization runs

Sync polls the external system on a fixed interval and imports matching open items.

• The interval is 15 minutes by default, set by the API setting Tickets:SyncIntervalMinutes (restart required). It is not shown in the UI.
• Each sync reads the 100 most recently updated items; older items are picked up only when they are updated.
• Closed items are never imported.
• An external edit updates the Polygent ticket only while the ticket is still Pending.
• Each imported item receives a back-link comment ("This task is managed in Polygent Ticket #N"), so the token needs write access to issues or work items.
• A background sync runs as a member of the workspace; a workspace with no assigned members is skipped.

GitHub setup

GitHub setup selects one issues repository for the workspace.

1. Open the workspace Tickets tab.
2. Set Source to GitHub and turn on Enable automatic sync.
3. Enter the issues repository URL and a token with repo scope (issues read/write and pull requests).
4. Add Label Filters if only selected issues should import. Every listed label must be present on an issue for it to match.
5. Save, then test with a non-critical issue.

GitHub has no outbound status sync: stage changes are not written back to issues.

Azure DevOps / TFS setup

Azure DevOps/TFS setup requires an HTTPS organization or collection URL and a project.

Field	Purpose
TFS / Azure DevOps URL	HTTPS organization or collection URL.
TFS PAT	Workspace token, used unless a user has saved a personal token for the workspace.
TFS Project Name	Target project.
Area Path Filters	Import items under any listed area path, including child areas.
Tag Filters	Import only items carrying every listed tag.
Status Sync Map	For each Polygent stage, the work-item state to set when a ticket enters it (Polygent → Azure DevOps only).
Default Fields	Values applied when creating Bugs from Polygent.

Changing the server (host or port) in the URL clears the saved workspace token and all personal tokens for the workspace; enter a new workspace token in the same update and ask users to re-save personal tokens. Changing only the collection path keeps tokens.

Users can save a personal token under Profile → TFS Tokens so sync, status updates, and pull requests run under their own identity; background operations fall back to the workspace token. For Azure DevOps, pull requests use the TFS token (personal or workspace), not the repository token.

Outbound status updates

When a ticket changes stage, Polygent sets the mapped work-item state. A failed update is retried up to 5 times with increasing delays (from about a minute up to several hours); a newer stage change replaces a pending older one. After the final attempt, or immediately for a permanent error such as a rejected state, the assigned developer (or the ticket creator) receives an inbox notification.

Do not map a non-final Polygent stage to Closed, Done, or Removed — the next sync treats that state as an external close and cancels the ticket.

Auto-Start Rules

Auto-Start Rules start a newly imported ticket with a Start Ticket Template when its tags or labels match a rule.

• Up to 20 rules per workspace. Every tag in a rule must match (case-insensitive); the first matching rule wins.
• Rules apply only on first import. Items matching a rule are imported even when they do not match the general tag or label filters; area-path filters and the GitHub issues repository still apply.
• The started ticket uses the template's model, workflow, branches, Plan setting, and session options, and is assigned to the syncing user.
• Auto-start requires a license that includes ticket automation.
• Imported title, body, and labels are scanned for instruction-like content. A flagged ticket is imported with an Injection scan badge but does not auto-start; review it and start it manually only if safe.

Test every rule with a harmless external item before production use, and keep matching tags specific.

External closure

External closure cancels the linked Polygent ticket on a later sync; it is always on.

A GitHub issue that is closed, or an Azure DevOps/TFS item in Closed, Done, or Removed, cancels the linked non-terminal ticket: active work stops, the cancellation is recorded, and capacity is released. These states are fixed and not configurable.

Pull requests

Tickets that reach the pull-request stage create and track pull requests through the workspace's ticket source.

The ticket shows per-repository pull-request state when several repositories changed, and completes only after every required pull request is merged. See PR status tracking.

Security and operations

Ticket Sync processes externally authored content with privileged credentials.

• Grant only the required issue, work-item, repository, and pull-request scopes.
• Rotate tokens on staff changes or suspected exposure.
• Restrict auto-start rules to trusted labels and projects.
• Review imported attachments and instructions before execution.
• Watch the inbox for failed status updates after outages or token rotation.
• Retest status mapping and filters after external workflow changes.

Troubleshooting

These checks cover common synchronization failures.

Symptom	Check
Nothing imports	Confirm Enable automatic sync, source, project or repository, token validity, filters, and that the workspace has assigned members. Wait for the next sync interval.
An older item never imports	Only the 100 most recently updated items are read; update the item externally.
GitHub issue is skipped	Check that it carries every label filter and belongs to the configured issues repository.
Azure item is skipped	Check area path, that it carries every tag filter, the project, and token access.
External edits are not reflected	The ticket has left Pending; later external edits are not applied.
Status does not update externally	Azure DevOps/TFS only. Verify the Status Sync Map, token write permission, and the failure notification in the inbox.
Ticket was canceled unexpectedly	The external item was closed, or a mapped state is Closed, Done, or Removed.
Auto-start did not run	Confirm rule tags, template validity, license, host capacity, that this was the first import, and whether the injection scan flagged it.
Tokens disappeared	The server host or port in the URL changed; re-enter the workspace token and personal tokens.
Pull request creation fails	Verify the ticket source is configured, token scopes, branch access, and changed repositories.

Ticket Sync does not replace external permission management, copy external history, or make external instructions trusted. Imported tickets use the standard ticket pipeline.