Jira Cloud Port

Purpose

This is the Harbor reference integration for the Jira Cloud REST API.

Use it when:

• building Jira Cloud actions in Harbor
• extending the Dock / Hub Jira Cloud entry
• teaching Codex or OpenClaw how to map an issue-tracking API into Harbor Ports and Harbor Actions without turning Harbor into a generic tenant-wide admin proxy

Harbor Port worksheet

Product

• Product: Jira Cloud REST API
• Publisher slug: atlassian
• Publisher name: Atlassian
• Category: Work Management
• Tags: jira, atlassian, issues, tickets, planning

Safe Harbor Port metadata

• Kind: http_api
• Label: Jira Cloud API
• Description: Jira Cloud API connection managed locally through Harbor.
• Base URL: https://your-domain.atlassian.net/
• Auth mode: header_token
• Auth header name: Authorization
• Auth token prefix: Bearer

Hidden local config

• authToken
• local tenant base URL override

Harbor stores the token locally only. Dock / Hub manifests must never contain it.

Harbor action design notes

Jira Cloud is a good Harbor fit when we keep search bounded, issue lookup explicit, and issue creation reviewable.

Good Harbor Jira starter actions:

• bounded GET search using typed JQL and pagination inputs
• explicit single-issue lookup by issue key or ID
• one reviewable POST route for issue creation
• requestBodyMode: "none" for reads
• requestBodyMode: "json" for the bounded create request body
• resultMode: "json_summary" for all starter actions

Avoid for now:

• broad Jira admin and tenant-configuration surfaces
• freeform passthrough of large field-selection or expansion grammars
• workflow transition, delete, bulk archive, and notification actions before policy review
• generic route forwarding across the Jira API

Starter Jira actions

Automatic read actions

• search-issues -> GET /rest/api/3/search/jql
• get-issue -> GET /rest/api/3/issue/{issueIdOrKey}

Approval-friendly write actions

• create-issue -> POST /rest/api/3/issue

Why these actions

These routes fit Harbor's current safe model because they:

• stay under one tenant-owned Jira Cloud origin that the operator configures locally
• use explicit issue identifiers or bounded query inputs instead of arbitrary path editing
• give agents a strong triage loop without exposing broad admin capability
• keep issue creation as a named, reviewable action instead of generic authenticated HTTP access

Action Model notes

For Jira actions, Harbor stores explicit route templates and typed parameter metadata such as:

• /rest/api/3/search/jql
• /rest/api/3/issue/{issueIdOrKey}
• /rest/api/3/issue

At execution time, callers supply values by location:

• input.query for search values such as JQL and pagination
• input.path.issueIdOrKey for single-issue lookup
• input.body for JSON issue creation payloads

Example issue search request:

{
  "query": {
    "jql": "project = OPS AND statusCategory != Done ORDER BY updated DESC",
    "maxResults": 25
  }
}

Example issue lookup request:

{
  "path": {
    "issueIdOrKey": "OPS-123"
  }
}

Example create request:

{
  "body": {
    "fields": {
      "project": {
        "key": "OPS"
      },
      "issuetype": {
        "name": "Task"
      },
      "summary": "Review Harbor import policy for Jira writes",
      "description": {
        "type": "doc",
        "version": 1,
        "content": [
          {
            "type": "paragraph",
            "content": [
              {
                "type": "text",
                "text": "Opened from Harbor after operator review."
              }
            ]
          }
        ]
      }
    }
  }
}

Harbor fills path placeholders safely, validates query values against stored schema, and keeps the request origin Harbor-owned.

Tenant configuration note

Jira Cloud is tenant-scoped. After importing from Dock / Hub, the operator must replace the placeholder base URL with the actual site URL, such as https://acme.atlassian.net/, before any action will work.

Safety note for issue creation

create-issue stays on require_approval because Jira writes can trigger workflow rules, notifications, automation, and downstream integrations. Harbor should treat that as an explicit, reviewable capability.

Suggested operator workflow

1. Import the Jira Cloud Dock entry from Dock / Hub.
2. Replace the placeholder base URL with your Jira Cloud tenant URL.
3. Configure the local Jira bearer token in Harbor Node with the scopes you need.
4. Use search-issues first to confirm the port is working.
5. Use get-issue to inspect a known ticket before adding write flows.
6. Keep create-issue on require_approval unless there is a very deliberate local policy reason not to.

Suggested agent workflow

1. Inspect the existing Jira Harbor Port.
2. Inspect live actions and drafts.
3. Propose additional fixed or tightly bounded Jira routes only.
4. Validate and test drafts.
5. Request publish instead of self-publishing unless Harbor explicitly allows it.

Agents should never:

• ask Harbor for the stored Jira token
• edit hidden auth directly
• widen Jira into a generic tenant-wide admin proxy
• hide tenant-specific targeting behind arbitrary URL input

Current update strategy

For now, Jira Cloud updates are manual:

• update the Dock / Hub Jira integration document in apps/hub/catalog/integrations/atlassian/jira-cloud-api.json
• bump the manifest version when the action set changes materially
• re-import into Harbor or create new drafts from the updated Dock entry

Future expansions such as transitions, comments, and edit flows are intentionally deferred until Harbor has clearer policy controls for mutation-heavy project tooling.

Official reference starting points

• Jira REST API v3 overview: https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/
• Issue search: https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issue-search/
• Issues: https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issues/
• OAuth scopes: https://developer.atlassian.com/cloud/jira/platform/scopes-for-oauth-2-3LO-and-forge-apps/