Backstage External Integration Conventions
These instructions apply to GitHub, Azure DevOps, and ServiceNow technical integrations. They are
authoritative for credential boundaries, provider modules, discovery, events, template actions,
and entity annotations in matched files; current provider documentation and stricter organization
security policy win on conflict.
Provider Credentials
- Keep technical integration credentials separate from sign-in providers.
- Prefer GitHub Apps, service principals, or managed identities over long-lived personal tokens
when supported.
- Store every secret externally and document owner, scope, rotation, and expiration.
- Validate webhook or service-hook authenticity.
Discovery and Actions
- Install only the provider modules required by the requested capability.
- Bound discovery by organization, project, repository, path, branch, schedule, and timeout.
- Treat repository publication and ServiceNow create, update, or delete actions as mutating.
- Validate entity annotations against the installed provider package.
Conventions
| Rule |
Rationale |
| Check community plugin status and peer dependencies. |
ServiceNow and Azure DevOps UI packages evolve independently from core. |
| Keep provider failures isolated and observable. |
One unavailable provider should not hide unrelated catalog data. |
| Use minimum scopes for enabled features. |
Integration tokens often cross many repositories or systems. |
Do / Do Not
| Do |
Do not |
| Use supported backend modules and extension points. |
Embed provider SDK calls throughout app code. |
| Test rate limits, denied access, and unavailable providers. |
Validate only the success path. |
| Approval-gate external mutations. |
Let templates mutate provider state silently. |
Checklist Before Opening a PR
References
1---2name: backstage-integrations3description: Apply Backstage external integration conventions for GitHub, Azure DevOps, and ServiceNow. Use when editing provider credentials, discovery, events, scaffolder modules, or entity annotations.4---56<!-- Generated from harness/github-copilot/plugins/backstage-expert/instructions/backstage-integrations.instructions.md by harness/claude-code/scripts/convert_from_copilot.py. Edit the source, not this file. -->78# Backstage External Integration Conventions910These instructions apply to GitHub, Azure DevOps, and ServiceNow technical integrations. They are11authoritative for credential boundaries, provider modules, discovery, events, template actions,12and entity annotations in matched files; current provider documentation and stricter organization13security policy win on conflict.1415## Provider Credentials1617- Keep technical integration credentials separate from sign-in providers.18- Prefer GitHub Apps, service principals, or managed identities over long-lived personal tokens19 when supported.20- Store every secret externally and document owner, scope, rotation, and expiration.21- Validate webhook or service-hook authenticity.2223## Discovery and Actions2425- Install only the provider modules required by the requested capability.26- Bound discovery by organization, project, repository, path, branch, schedule, and timeout.27- Treat repository publication and ServiceNow create, update, or delete actions as mutating.28- Validate entity annotations against the installed provider package.2930## Conventions3132| Rule | Rationale |33| --- | --- |34| Check community plugin status and peer dependencies. | ServiceNow and Azure DevOps UI packages evolve independently from core. |35| Keep provider failures isolated and observable. | One unavailable provider should not hide unrelated catalog data. |36| Use minimum scopes for enabled features. | Integration tokens often cross many repositories or systems. |3738## Do / Do Not3940| Do | Do not |41| --- | --- |42| Use supported backend modules and extension points. | Embed provider SDK calls throughout app code. |43| Test rate limits, denied access, and unavailable providers. | Validate only the success path. |44| Approval-gate external mutations. | Let templates mutate provider state silently. |4546## Checklist Before Opening a PR4748- [ ] Provider packages and status match the target Backstage version.49- [ ] Credentials are external, least-privilege, owned, and rotatable.50- [ ] Discovery, schedules, webhooks, and annotations are bounded and valid.51- [ ] Mutating actions are visible and approval-gated.52- [ ] Positive, denied, throttled, and unavailable-provider paths are tested.53- [ ] No unrelated edits or credentials remain.5455## References5657- [Backstage integrations](https://backstage.io/docs/integrations/)58- [GitHub Apps](https://backstage.io/docs/integrations/github/github-apps)59- [Azure DevOps integration](https://backstage.io/docs/integrations/azure/locations)
paulasilvatech