# Backstage Integrations

> Use when editing Backstage integrations with GitHub, Azure, Azure DevOps, or other external providers.

- Skill: `paulasilvatech/backstage-integrations-2` (Agent Skill)
- Install (CLI): `npx skillmds@latest add paulasilvatech/backstage-integrations-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/paulasilvatech/backstage-integrations-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: paulasilvatech (https://skillmd.com/u/paulasilvatech)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/paulasilvatech/backstage-integrations-2

---


<!-- Generated from harness/github-copilot/plugins/open-horizons-platform/instructions/backstage-integrations.instructions.md by harness/claude-code/scripts/convert_from_copilot.py. Edit the source, not this file. -->

# Backstage External Integrations

## Conventions

- Use the least-privilege credential type supported by the provider, preferring GitHub Apps, managed identity, workload identity, or short-lived delegated tokens.
- Keep provider sign-in, catalog discovery, backend service access, and user-delegated actions as separate trust boundaries.
- Resolve credentials from environment-backed secret stores and keep them out of catalog entities, logs, and frontend config.
- Scope organizations, repositories, projects, tenants, and subscriptions explicitly; reject requests outside the configured boundary.
- Bound scheduled discovery and event processing with stable task IDs, timeouts, retries, and idempotency.
- Validate webhook signatures and event provenance before processing.
- Normalize provider failures into safe integration errors while retaining redacted correlation metadata.
- Keep provider-specific code behind typed adapters so catalog and UI contracts remain stable.

## Verification

- Integration tests use fixtures or mocks rather than production credentials.
- Permission scopes are documented by the owning configuration and match actual operations.
- Discovery, webhook replay, throttling, and provider-unavailable paths remain deterministic.

## Do / Do Not

| Do | Do not |
| --- | --- |
| Keep providers behind typed adapters and test bounded failure behavior. | Couple catalog or UI contracts to provider-specific response objects. |
| Use fixtures and least-privilege scopes. | Test with production credentials or broaden permissions implicitly. |

## Checklist Before Opening a PR

- [ ] The change matches this instruction's `applyTo` scope.
- [ ] Adapter contracts and permission scopes match actual operations.
- [ ] Discovery, replay, throttling, and unavailable-provider cases are tested.
- [ ] Fixtures contain no production credential or private tenant data.
- [ ] No unrelated edits or unresolved placeholders remain.