Skip to content
Trilogy Care Logo TC Docs

Jira Sync Scripts

Jira Sync Scripts

This directory contains scripts for synchronizing TC Portal’s initiative structure with Jira.

Available Scripts

jira-full-sync.php

Performs a comprehensive sync of all initiatives and epics from Jira to the local structure.

What it does:

  • Queries Jira for ALL initiatives and child epics
  • Compares with current sync-manifest.json
  • Creates folders for new initiatives and epics
  • Archives closed epics to initiative-scoped ARCHIVED folders
  • Updates sync-manifest.json with latest data
  • Generates comprehensive sync report

Usage:

Terminal window
# Normal sync (makes changes)
php .claude/scripts/jira-full-sync.php


# Dry run (preview changes without making them)
php .claude/scripts/jira-full-sync.php --dry-run

Requirements:

  • Jira credentials must be configured in .env:
    • JIRA_EMAIL - Your Jira email
    • JIRA_API_TOKEN - Your Jira API token

Output:

  • Updates sync-manifest.json
  • Creates backup sync-manifest.json.backup
  • Generates SYNC-REPORT-YYYY-MM-DD.md
  • Creates folders for new initiatives/epics
  • Archives closed epics to [INITIATIVE]/ARCHIVED/YYYY-MM_[EPIC]/

Archive Structure

As of 2025-11-09, archived epics are stored in initiative-scoped ARCHIVED folders:

.trilogy/initiatives/
└── TP-XXXX-Initiative-Name/
    ├── ARCHIVED/
    │   ├── 2025-11_TP-YYYY-PREFIX-Epic-Name/
    │   │   ├── DUMP/
    │   │   └── archive-metadata.json
    │   └── 2025-11_TP-ZZZZ-PREFIX-Another-Epic/
    │       ├── DUMP/
    │       └── archive-metadata.json
    ├── TP-AAAA-PREFIX-Active-Epic-1/
    └── TP-BBBB-PREFIX-Active-Epic-2/

This replaces the previous global .trilogy/initiatives/ARCHIVED/ folder.

Getting Jira Credentials

To set up Jira API access:

  1. Go to: https://id.atlassian.com/manage-profile/security/api-tokens
  2. Click “Create API token”
  3. Copy the token
  4. Add to .env: 
    JIRA_EMAIL=your.email@trilogycare.com
    JIRA_API_TOKEN=your_api_token_here

Troubleshooting

Error: JIRA_EMAIL and JIRA_API_TOKEN must be set in .env file

  • Make sure credentials are configured in .env
  • Restart your terminal/IDE after adding credentials

Error: Failed to query initiatives from Jira

  • Check your API token is valid
  • Ensure you have permission to view initiatives/epics in Jira
  • Verify network connectivity to trilogycare.atlassian.net

Error: Epic not found in Jira

  • Epic may have been deleted in Jira
  • Epic may have been moved to different initiative
  • Check Jira web interface to verify epic status

Integration with Product Manager Agent

The Product Manager Agent can invoke these scripts via /jira-sync command:

/jira-sync              # Full sync
/jira-sync --dry-run    # Preview changes

The agent will parse the sync report and present it in a user-friendly format.