ArdSaor

DriftGuard for Jira — Documentation

DriftGuard is an Atlassian Forge app that monitors Jira configuration drift for boards and filters. It snapshots configuration on a schedule, compares changes, and presents a clear timeline with human readable diffs. Optional Jira issue notifications keep teams informed.

Contents

Supported products and requirements

  • Jira Cloud.
  • Board monitoring requires Jira Software on the site.
  • Filter monitoring works on Jira Cloud sites that support saved filters.
  • Admin access is required to install and configure the app.

What DriftGuard monitors

  • Boards: column and status mappings, WIP limits, ranking field, estimation settings, and other board configuration.
  • Filters: JQL, name and description, owner metadata, and share or edit permissions.

DriftGuard does not read issue content. It only stores configuration metadata needed to compare snapshots and explain what changed.

How DriftGuard works

  1. When you add a monitor, DriftGuard captures a baseline snapshot.
  2. On a schedule, DriftGuard fetches configuration for each monitored target.
  3. Configuration is normalized and hashed for stable, reliable diffing.
  4. If the hash changes, DriftGuard stores a new snapshot and generates a change event.
  5. The admin timeline shows detected changes with summaries and severity.

DriftGuard is read first. It does not edit board or filter configuration. The only write action is optional Jira issue creation for notifications.

Installation

  1. Install DriftGuard from the Atlassian Marketplace (Jira Cloud).
  2. The app adds a Jira admin page named DriftGuard Admin.
  3. Open the admin page to configure monitors and settings.

Quick start

  1. Open DriftGuard Admin from Jira settings or Apps.
  2. Add a board or filter monitor.
  3. Confirm the baseline snapshot (automatic on add).
  4. Make a safe test change in Jira (board config or filter JQL).
  5. Wait for the next scheduled snapshot or use Capture snapshot.
  6. Review the change in the timeline and open the diff detail.

Managing monitors

  • Add monitor: Select a board or filter to start tracking.
  • Enable or disable: Disabled monitors are skipped by scheduled snapshots.
  • Capture snapshot: Force a snapshot now, useful after intentional changes.
  • Remove: Removing a monitor deletes its stored snapshots and events.
  • Limits: Up to 100 monitors per installation.

Snapshots, cadence, and retention

  • Cadence: Hourly by default. You can switch to daily in settings.
  • Detection time: DriftGuard reports the time a snapshot detected a change.
  • Retention: Default retention is 30 days, with a cap of 100 snapshots per target.
  • Batching: Targets are processed in batches to keep runs reliable at scale.

If you choose daily cadence, the app still runs hourly but throttles snapshots so only one daily run is performed.

Change timeline and diff detail

  • Timeline: Chronological list of detected changes with target name, summary, and severity.
  • Diff detail: Human readable changes, full normalized configuration, and raw JSON diff view.
  • Severity: Info, warning, and critical help prioritize changes that may affect workflows.

The diff view is designed to answer: what changed, when, and how it affects behavior. DriftGuard does not claim who changed it unless Jira provides reliable attribution.

Notifications (optional)

DriftGuard can create Jira issues when changes are detected. This is opt in and relies on your Jira notification schemes.

  • Choose a project and issue type for notification issues.
  • Set a minimum severity (all, warning, or critical).
  • Optionally include diff details in the issue description (up to 10 items).
  • Select recipients to @mention in notification comments.

Notifications are best effort. If Jira issue creation fails, DriftGuard logs the error and continues snapshot processing.

Settings

  • Snapshot cadence: Hourly or daily.
  • Retention days: Controls how long snapshots and events are kept.
  • Notifications: Project, issue type, severity threshold, recipients, and diff inclusion.

Permissions and data access

DriftGuard uses Atlassian Forge and requests only the scopes needed to monitor configuration and deliver optional notifications.

  • read:jira-work - read board and filter configuration metadata.
  • read:jira-user - user search for notification recipients.
  • read:board-scope:jira-software - board list and configuration access.
  • read:board-scope.admin:jira-software - admin level board configuration access.
  • read:filter:jira - filter search and filter details.
  • read:issue-details:jira - issue metadata access for notification configuration and validation.
  • write:jira-work - create Jira issues for notifications (optional).
  • read:project:jira - list projects for notification settings.
  • read:workflow:jira - reserved for workflow drift monitoring (not enabled by default).
  • manage:jira-project - reserved for workflow and scheme checks (not enabled by default).
  • manage:jira-configuration - reserved for workflow scheme drift detection (experimental).
  • storage:app - store snapshots, settings, and change events.

Data stored and retention

  • Monitor targets: IDs, display names, enabled state, and status.
  • Snapshots: normalized board or filter configuration only.
  • Change events: summaries, severity, timestamps, and diff paths.
  • Settings: cadence, retention, and notification configuration.
  • Cursor state: batch processing progress.

DriftGuard does not store issue content. Recipient identities are stored as account IDs, not email addresses.

Removing a monitor deletes its snapshots and events. Uninstalling the app removes DriftGuard storage from your site.

Security and privacy

  • Runs entirely on Atlassian Forge.
  • No external servers or third party data processors.
  • Data is stored in Forge storage within Atlassian infrastructure.
  • Only configuration metadata is stored, not issue content.

Known limitations

  • Detection time is based on snapshot cadence, not the exact change time.
  • Some private boards or filters may not be accessible to the app.
  • Scheduled snapshots run in app context, not user context.
  • Workflow monitoring is not enabled in the UI by default.

Troubleshooting

I cannot add a board monitor

  • The app may not have access to the board configuration.
  • Try a different board or ensure the board filter is shared appropriately.

I cannot add a filter monitor

  • Personal or private filters are not accessible to scheduled snapshots.
  • Share the filter with a project or group so the app can access it.

No changes are showing

  • Wait for the next snapshot run or use Capture snapshot.
  • Check that the monitor is enabled and cadence is not set to daily.

Notifications are not firing

  • Confirm notifications are enabled and a project and issue type are selected.
  • Check the severity threshold matches the change severity.
  • Verify your Jira notification scheme for the project.

FAQ

Does DriftGuard change Jira configuration?

No. DriftGuard is read first. It never edits boards or filters. The only write action is optional Jira issue creation for notifications.

Does DriftGuard tell me who made the change?

No. Jira does not provide reliable attribution for all configuration changes, so DriftGuard does not guess.

Can I export changes?

Export is not available in the current release.

Does it support workflow monitoring?

Workflow monitoring is not enabled in the UI by default. Contact support if you want to discuss early access.

Support

Need help or have a feature request? Contact us via the Marketplace listing support link or ArdSaor Support. Include your Jira site URL and a short description of the action you were taking.