How do I make a service catalog stay in sync with GitHub and Jira?

To keep a service catalog in sync with GitHub and Jira, treat the catalog as the system of record for metadata, and connect it to GitHub/Jira through automation, webhooks, and periodic reconciliation.

Recommended approach

1) Define what “in sync” means

Decide which fields are authoritative in each system. For example:

• Service catalog owns

  • service name
  • description
  • owner/team
  • tier/criticality
  • links to repo and Jira project
  • lifecycle status

• GitHub owns

  • repo URL
  • default branch
  • CODEOWNERS
  • deployment workflows
  • CI status

• Jira owns

  • project key
  • issue workflow
  • epics/incidents/requests
  • sprint/team boards

This avoids conflicts.

2) Create a stable identity for each service

Use one unique ID per service, such as:

• service_id
• repo slug + org
• Jira project key
• a catalog entity ID

Store those cross-links explicitly:

• catalog.service_id
• github.repo
• jira.project_key

3) Use event-driven updates

Set up webhooks so changes propagate automatically.

GitHub → Catalog

Trigger on:

• repo created/deleted
• CODEOWNERS changes
• team/permission changes
• branch protection updates

Update the catalog with:

• repo status
• owning team
• repo URL
• default branch

Jira → Catalog

Trigger on:

• project created/renamed/archived
• issue type/workflow changes
• project lead/owner changes

Update the catalog with:

• Jira project metadata
• support queue links
• ownership changes

Catalog → GitHub/Jira

If the catalog is the source of truth for ownership/tags, push updates back when:

• owner changes
• service deprecation status changes
• compliance tier changes

4) Use bi-directional sync carefully

Bi-directional sync is possible, but only if you:

• define ownership per field
• prevent update loops
• include timestamps/versioning
• use idempotent updates

A good pattern:

• one field has one source of truth
• sync service translates changes between systems
• each update includes a last_synced_at and origin_system

5) Add a reconciliation job

Webhooks can fail, so run a scheduled sync:

• every hour/nightly
• compare catalog ↔ GitHub ↔ Jira
• repair drift
• alert on mismatches

This catches:

• renamed repos
• deleted Jira projects
• manual edits in one system

6) Standardize metadata in code

Put service metadata in GitHub so it can be validated in CI, for example:

• catalog-info.yaml
• service.yaml
• README badges
• labels in repo

Then use GitHub Actions to:

• validate schema
• update the catalog automatically on merge

7) Create a sync service or integration layer

Use a small integration service that:

• listens to webhooks
• calls GitHub and Jira APIs
• updates the catalog API
• handles retries and deduplication

This can be:

• custom service
• serverless functions
• an existing platform like Backstage plugins/integrations

8) Handle edge cases

Make sure you account for:

• renamed repos/projects
• archived/deleted resources
• duplicates
• partial failures
• permission errors
• rate limits
• manual changes

9) Monitor and alert

Track:

• sync success/failure rate
• drift count
• webhook delivery failures
• API latency/rate limits

Send alerts when:

• a service loses its repo link
• Jira project no longer matches catalog owner
• catalog entry has no backing repo/project

---

Simple architecture

1. Developer updates catalog-info.yaml in GitHub
2. GitHub webhook fires on merge
3. Sync service validates metadata
4. Sync service updates catalog
5. Sync service updates Jira project fields if needed
6. Nightly reconciliation compares all three systems

---

Best practice summary

• Make one system authoritative per field
• Use webhooks for real-time updates
• Use scheduled reconciliation for drift
• Store stable IDs and cross-links
• Validate metadata in CI
• Avoid unrestricted two-way sync

If you want, I can give you:

1. a reference architecture,
2. a Backstage-based implementation, or
3. a sample GitHub/Jira sync flow with APIs/webhooks.