Workflows & Recipes

This page collects production-style ajat recipes with full command sequences, for teams that need repeatable, estate-scale operations rather than one-off command examples. Each recipe follows the same discipline: validate, discover scope, export or inspect, then run the higher-impact operation only after the operator can see the plan.

Command discovery on a new tenant

The safest way to explore a tenant you have not operated before is to validate, then look, then read, then plan.

ajat doctor                                        # config, license, credentials, API access
ajat tree --short                                  # available command families
ajat search --limit 10                             # confirm the account can read rule summaries
ajat export --output-dir ./jira-automations-backup # create the local catalog
ajat report inventory --input-dir ./jira-automations-backup --output-file inventory.html

Only after the inventory report has been reviewed should you reach for ajat diff, ajat rule, or ajat import with --dry-run.

Organization-wide quarterly review

Use this when a governance owner needs a full, shareable picture of the automation estate: what exists, what is risky, what is duplicated, and what needs cleanup.

ajat doctor --output-dir ./reviews/q2
ajat export --output-dir ./reviews/q2 --redact-sensitive-fields
 
ajat report inventory   --input-dir ./reviews/q2 --output-file q2-inventory.html
ajat report collision   --input-dir ./reviews/q2 --output-file q2-collisions.html
ajat report consistency --input-dir ./reviews/q2 --output-file q2-consistency.html
ajat report risk        --input-dir ./reviews/q2 --output-file q2-risk.html

How to read the outputs:

• Inventory is the baseline — every rule by scope, with per-rule flow diagrams and the integration footprint of every external service the estate reaches.
• Risk triages what needs attention: silent failures, orphaned ownership, stale-but-enabled rules, and high-frequency schedules, scored A–F and attributed by project.
• Collision surfaces consolidation candidates — near-duplicate rules copy-pasted across projects.
• Consistency flags naming, label, and ownership hygiene to clean up.

--redact-sensitive-fields asks Jira to mask sensitive values so the review artifacts are safe to share. See HTML Reports for the report catalogue and secure sharing guidance.

Daily drift gate in CI

Use this to fail a pipeline (or just alert) when the live automation estate drifts from a reviewed baseline.

ajat export --output-dir ./current --no-progress
ajat diff ./baseline ./current --check

ajat diff --check returns a non-zero exit code when differences are found, which is what turns it into a gate. Store Jira credentials as CI secrets and use structured logging for the run record:

export AJAT_JIRA_DOMAIN=acme.atlassian.net
export AJAT_JIRA_USERNAME=$JIRA_USER
export AJAT_JIRA_API_TOKEN=$JIRA_TOKEN
 
ajat export --output-dir ./current --no-progress \
  --log-file ./ajat.log --log-format json
ajat diff ./baseline ./current --check

When the gate fires, promote the reviewed snapshot to become the new baseline so the next run compares against approved state.

Incident pause and recovery

Use this to quickly pause every rule in an affected project scope during an incident, then re-enable them cleanly once the incident is resolved. Every mutation is previewed with --dry-run before it is applied.

# 1. Snapshot before touching anything — this is your evidence and undo point.
ajat export --output-dir ./incident-snapshot
 
# 2. Preview the pause, scoped to the affected project.
ajat rule disable --input-dir ./incident-snapshot \
  --scope ari:cloud:jira:<tenant>:project/ALPHA \
  --dry-run
 
# 3. Apply the pause.
ajat rule disable --input-dir ./incident-snapshot \
  --scope ari:cloud:jira:<tenant>:project/ALPHA \
  --yes

After the incident is resolved, refresh the catalog and re-enable the same scope:

ajat export --output-dir ./incident-snapshot
ajat rule enable --input-dir ./incident-snapshot \
  --scope ari:cloud:jira:<tenant>:project/ALPHA \
  --yes

Bulk rule operations select against an auditable local export, not an invisible server query. See Bulk Rule Operations for the full selector set (UUID, label, name glob, author, scope, state).

Same-tenant disaster recovery

Use this when a rule was wrecked or deleted and you need to restore the last known-good state into the same tenant, keeping original UUIDs so external references keep working.

# 1. Preview the restore.
ajat import --input-dir ./last-known-good --dry-run
 
# 2. Apply it (default --uuid-strategy=preserve keeps original UUIDs).
ajat import --input-dir ./last-known-good --yes
 
# 3. Verify by exporting the current state and diffing against the snapshot.
ajat export --output-dir ./post-restore
ajat diff ./last-known-good ./post-restore

A clean diff after the restore is your evidence that the tenant now matches the snapshot you imported. See Import and Restore for the plan, the state file, and the UUID strategy.

Sandbox-to-production promotion

Use this to promote rules validated in a sandbox tenant into production. Fresh UUIDs avoid collisions, and --scope-map rewrites each sandbox project ARI to its production equivalent.

# 1. Dry-run to confirm the plan and the scope-map entry count.
ajat import --input-dir ./sandbox-export --uuid-strategy=new \
  --scope-map ari:cloud:jira:sandbox:project/APP=ari:cloud:jira:prod:project/APP \
  --dry-run
 
# 2. Apply the promotion.
ajat import --input-dir ./sandbox-export --uuid-strategy=new \
  --scope-map ari:cloud:jira:sandbox:project/APP=ari:cloud:jira:prod:project/APP \
  --yes
 
# 3. Export production afterward and keep it as evidence.
ajat export --output-dir ./post-promotion

Run one --scope-map entry per project ARI that differs between the source and target tenants. The dry-run plan reports the active entry count so you can confirm the right number of mappings loaded before applying.

Cleanup of deprecated disabled rules

Use this to permanently remove rules that were disabled and tagged for retirement. Deletion is only permitted on DISABLED rules, so enabled candidates are disabled first.

ajat export --output-dir ./jira-automations-backup
 
ajat rule delete --input-dir ./jira-automations-backup \
  --label deprecated \
  --state DISABLED \
  --dry-run
 
ajat rule delete --input-dir ./jira-automations-backup \
  --label deprecated \
  --state DISABLED \
  --yes

If rules tagged deprecated are still enabled, disable them first, refresh the export, then delete:

ajat rule disable --input-dir ./jira-automations-backup --label deprecated --yes
ajat export --output-dir ./jira-automations-backup
ajat rule delete --input-dir ./jira-automations-backup --label deprecated --state DISABLED --yes

As an alternative during a restore, ajat import --prune removes DISABLED orphans that are absent from a trusted source export.

Invoke a manual rule for triage

Use this to discover and run a manually-triggered rule against a specific target — for example, re-triaging an issue during an incident.

ajat rule manual list --target PROJ-123
 
ajat invoke <rule-uuid> \
  --target PROJ-123 \
  --input reason="re-triage" \
  --dry-run
 
ajat invoke <rule-uuid> \
  --target PROJ-123 \
  --input reason="re-triage" \
  --yes

See Invoke Manual Rules for target ARIs, issue-key resolution, and typed input JSON.

Recommended sequence for customer-facing runs

1. confirm readiness with ajat doctor
2. discover scope with ajat search and a first ajat export
3. build the reports the audience needs (inventory as baseline, risk to triage)
4. track change over time with ajat diff between snapshots
5. treat every mutation as plan-first — --dry-run, read the plan, then --yes