GATE Watcher — Jira

Self-hosted daemon that monitors your Jira Cloud projects for issue updates, comments, and transitions, pushing them to GATE for security processing. Your Jira credentials never leave your machine.

How it works

Your Machine (Watcher)              GATE Cloud
┌─────────────────────┐        ┌──────────────────┐
│ Jira API polling     │───────>│ Security pipeline │
│ (creds stay HERE)    │<───────│ (redact, policy,  │
│                      │ poll   │  audit, forward)  │
└─────────────────────┘        └──────────────────┘

Quick Start (CLI)

cd gate-watcher-jira
npm install

# Create .env (or pass env vars directly)
cp .env.example .env
# Fill in GATE_KEY, GATE_INTEGRATION_ID, and Jira credentials

npm start

On first run with OAuth, the browser opens automatically — click Allow, and you're connected.

Auth Modes

OAuth 2.0 (recommended)

Browser-based authorization. No manual tokens or emails needed.

1. Register an app at developer.atlassian.com/console/myapps
2. Set callback URL to http://localhost:*/callback
3. Enable scopes: read:jira-work, write:jira-work, read:jira-user, offline_access
4. Set JIRA_CLIENT_ID and JIRA_CLIENT_SECRET in .env
5. Run the watcher — browser opens, click Allow, done

Tokens are stored in ~/.gate/jira-oauth.json and auto-refresh. Use --auth to re-authorize or --logout to clear stored tokens.

API Token (headless / CI)

For environments without a browser.

1. Create an API token at id.atlassian.com/manage-profile/security/api-tokens
2. Set JIRA_DOMAIN, JIRA_EMAIL, and JIRA_TOKEN in .env

Embed in Your App (SDK)

npm install @anura-gate/watcher-jira

With OAuth

const { GateJiraWatcher } = require("@anura-gate/watcher-jira");

const watcher = new GateJiraWatcher({
  gateKey: "gk-xxx",
  integrationId: "int_xxx",
  oauth: {
    accessToken: "eyJ...",
    cloudId: "abcd-1234-...",
    siteUrl: "https://yourcompany.atlassian.net",
  },
  projects: ["PROJ", "ENG"], // optional — omit to watch all projects
});

await watcher.start();

With API Token

const watcher = new GateJiraWatcher({
  gateKey: "gk-xxx",
  integrationId: "int_xxx",
  jiraDomain: "yourcompany.atlassian.net",
  jiraEmail: "[email protected]",
  jiraToken: "ATATT3x...",
  projects: ["PROJ", "ENG"],
});

await watcher.start();

Listening to Events

watcher.on("ready", (displayName) => {
  console.log(`Jira connected: ${displayName}`);
});

watcher.on("event", (event, result) => {
  console.log(`Event: ${event.eventType}, Issue: ${event.content.metadata.issueKey}`);
  console.log(`Security actions: ${result.securityActions}`);
});

watcher.on("action_result", ({ action, success, error }) => {
  console.log(`${action}: ${success ? "done" : error}`);
});

// Later...
await watcher.stop();

Detected Events

| Event Type | Trigger | |---|---| | issue_transitioned | Status changed (e.g. To Do → In Progress) | | issue_assigned | Assignee changed | | issue_resolved | Resolution set (Done, Won't Fix, etc.) | | comment_added | New comment on an issue | | priority_changed | Priority changed | | labels_changed | Labels added or removed | | sprint_changed | Issue moved to a different sprint | | issue_updated | Summary, description, or other field changed |

Outbound Actions

GATE can queue actions for the watcher to execute locally:

| Action | Required Params | Optional Params | |---|---|---| | create_issue | project, summary | description, issueType, assignee, priority, labels | | add_comment | issueKey, body | — | | transition_issue | issueKey, transition | — | | assign_issue | issueKey | accountId (null = unassign) | | update_issue | issueKey | summary, description, priority, labels |

SDK Events

| Event | Args | Description | |---|---|---| | ready | (displayName) | Connected to Jira | | event | (event, result) | Jira event processed by GATE | | action | (action) | Outbound action received from GATE queue | | action_result | ({ actionId, action, success, result, error }) | Outbound action completed | | gate_error | ({ path, status, error }) | GATE API call failed | | jira_error | ({ path, error }) | Jira API call failed | | limit_reached | (type) | Plan limit hit | | stopped | — | Watcher fully shut down |

SDK Options

| Option | Required | Default | Description | |---|---|---|---| | gateKey | Yes | — | Virtual key (gk-xxx) | | integrationId | Yes | — | Integration ID (int_xxx) | | oauth | * | — | OAuth credentials ({ accessToken, cloudId, siteUrl }) | | jiraDomain | * | — | Jira Cloud domain (yourcompany.atlassian.net) | | jiraEmail | * | — | Atlassian account email | | jiraToken | * | — | Jira API token | | gateUrl | No | "https://anuragate.com" | GATE cloud URL | | projects | No | [] | Project keys to watch. Empty = all | | pollInterval | No | 30000 | ms between Jira API polls | | heartbeatInterval | No | 30000 | ms between heartbeats | | sessionId | No | — | Session ID for multi-tenant use | | sessionLabel | No | — | Human-readable session label | | sessionMetadata | No | {} | Arbitrary metadata for the session |

* Either oauth or all three of jiraDomain + jiraEmail + jiraToken are required.

Environment Variables

| Variable | Required | Description | |---|---|---| | GATE_KEY | Yes | Your GATE virtual key | | GATE_INTEGRATION_ID | Yes | Integration ID from the dashboard | | JIRA_CLIENT_ID | OAuth | Atlassian OAuth app client ID | | JIRA_CLIENT_SECRET | OAuth | Atlassian OAuth app client secret | | JIRA_DOMAIN | API Token | Jira Cloud domain (yourcompany.atlassian.net) | | JIRA_EMAIL | API Token | Atlassian account email | | JIRA_TOKEN | API Token | Jira API token | | JIRA_PROJECTS | No | Comma-separated project keys: PROJ,ENG | | GATE_URL | No | Custom GATE cloud URL | | WEB_PORT | No | Port for the dev dashboard (CLI only) |

CLI Flags

| Flag | Description | |---|---| | --auth | Force re-authorization (discard stored OAuth tokens) | | --logout | Clear stored OAuth tokens and exit |

Security Model

• Jira credentials stored locally on YOUR machine (.env or ~/.gate/jira-oauth.json)
• GATE cloud never sees or stores your Jira credentials
• All event content passes through GATE's security pipeline (redaction, policies, audit)
• Billing, limits, and security enforced server-side