Ticket Sync
Ticket Sync imports external work items into a workspace and can return configured status changes while preserving the Polygent ticket workflow.
Supported integrations
Integrations use dedicated workspace settings and credentials.
| Integration | Supported behavior |
|---|---|
| GitHub | Import issues, create issues, filter by labels, and create and track pull requests. |
| Azure DevOps / TFS | Import work items, create Bugs, filter by area path or tags, map statuses, and create and track pull requests. |
Use a dedicated least-privilege personal access token. Ticket-sync credentials are independent from repository credentials used by sessions.
GitHub setup
GitHub setup selects one issues repository for the workspace.
- Open workspace Tickets Configuration.
- Set Ticket Source to GitHub and enable sync.
- Enter the issues repository URL and a token with required issue permissions.
- Add label filters if only selected issues should import.
- Save, then test with a non-critical issue.
Confirm both import and any enabled outbound update before applying auto-start rules.
Azure DevOps / TFS setup
Azure DevOps/TFS setup requires an explicit HTTPS organization or collection URL and project. Tokens are bound to that server authority: changing the authority clears saved workspace and personal tokens, so enter a new workspace token in the same update or add personal tokens again afterward.
| Field | Purpose |
|---|---|
| TFS URL | Trusted HTTPS organization or collection URL. |
| TFS PAT | Workspace credential, unless an eligible personal token is used. |
| TFS Project | Required target project. |
| Area Path Filters | Limit imported items by area. |
| Tag Filters | Limit imported items by tags. |
| Status Mapping | Map Polygent ticket stages to outbound work-item states. |
| Default Fields | Values applied when creating external Bugs. |
Save a personal Azure DevOps token under Profile → TFS Token Management when operations should use the current user's identity. Personal tokens are workspace-scoped.
Auto-Start Rules
Auto-Start Rules apply a Start Ticket Template when external tags or labels match a configured rule.
Items matching an auto-start rule are eligible for import even when they do not match the general tag or label filters. Every tag in one rule must match. Azure DevOps/TFS area-path filters and the configured GitHub issues repository still limit which items can import.
Configure up to 20 rules per workspace. Use rules to select a model, workflow, branches, priority, assignments, and session options. Imported title, body, and labels are treated as untrusted content. A ticket flagged for suspicious instructions is imported 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. Keep the matching tags specific and ensure the selected host has capacity.
External closure
External closure can cancel a linked non-terminal ticket on a later sync.
Closing a GitHub issue or moving an Azure DevOps/TFS item to a configured closed state cancels active work, records the cancellation, releases capacity, and updates dependent work according to the ticket pipeline. Confirm status mappings before enabling this behavior so non-terminal external states are not treated as closed.
Pull requests
Tickets that reach the pull-request stage create and track pull requests using the configured integration and repository credentials.
The ticket shows per-repository pull-request state where multiple repositories changed. A ticket completes only after the required pull requests are merged. Open the ticket details to inspect conflicts, closed requests, or creation failures. See PR status tracking.
Security and operations
Ticket Sync processes externally authored content and privileged credentials.
- Grant only 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.
- Monitor failed status updates after outages or token rotation.
- Test mappings and filters after external workflow changes.
Troubleshooting
These checks cover common synchronization failures.
| Symptom | Check |
|---|---|
| Nothing imports | Confirm sync is enabled, source and project/repository are correct, token is valid, and filters match the test item. |
| GitHub issue is skipped | Check label filters and whether the issue belongs to the configured issues repository. |
| Azure item is skipped | Check item type, area path, tags, project, and token access. |
| Status does not update externally | Verify status mapping, outbound token permissions, and the latest visible sync failure. |
| Auto-start did not run | Confirm rule tags, template validity, host capacity, and whether untrusted-content review blocked automatic start. |
| External close did not cancel | Confirm the item is linked, the external state is configured as closed, and the Polygent ticket is not already terminal. |
| Pull request creation fails | Verify repository credentials, branch access, changed repositories, and integration permissions. |
Ticket Sync does not replace external permission management, copy arbitrary external history, or make external instructions trusted. External tickets otherwise use the standard ticket pipeline.