Starhive integration for Atlassian Jira

Starhive Integration for Jira adds a custom field type to Jira Cloud that displays Starhive objects on issues, and lets you embed Starhive pages directly into a Jira project.

Setting up the custom field

Once the app is installed, admins can create a custom field of type Starhive object or Starhive object cascade (in the advanced section), through Jira's normal custom field setup. Authentication uses OAuth2; some features additionally need a Personal Access Token.

Starhive object field

Select a workspace and a type to fetch objects from, optionally narrowed with a StarQL query. Pick up to three attributes to show alongside the object's label when selecting it, and configure whether the field accepts zero-to-one or zero-to-many objects (safe to change later — existing values aren't affected). The field supports multiple independent contexts, each with its own workspace/query configuration.

Starhive object cascade field

A cascade field lets a user make multi-level selections, where each level filters the next. Choose one workspace as the source for every level; each level then has its own StarQL query, and can reference an earlier level's selection with {{fieldName}} placeholder syntax. There's no fixed object type per level — parent levels narrow the options, and the final (leaf) level holds the objects actually shown in read/list views. Each level can optionally allow multiple selections, and a preview mode lets you test the cascading behavior live.

Filtering by the logged-in Jira user: reference their email with the ${emailCurrentUser} placeholder in a level's StarQL:

@Type = Employee AND userAttribute = userEmail(${emailCurrentUser})

caution

Changing a field's workspace configuration makes every existing link to a Starhive object behave as if it no longer exists.

Admin configuration (Manage apps)

Store a Personal Access Token in the app's admin page, for two purposes:

StarQL in JQL (optional) — without a token, changes to a Starhive object can take up to 7 days to show up in JQL results; with one, the app refreshes stale cache daily (or immediately, via "Refresh stale data").
Jira Service Management (mandatory) — required to configure Starhive custom fields on a JSM portal request type. The same token is used for every custom field added to JSM, so create it with a user that has adequate Starhive permissions.

Embedding Starhive pages in a project

The integration adds a Starhive navigation entry to every Jira project, where a project (or Jira) admin can configure one or more Starhive site pages as tabs.

Prerequisites: access to a Starhive account whose workspace contains the site, OAuth2 consent (first time only), and an existing site/page to embed.

Add a page: open Starhive in project navigation → + → choose Workspace → Site → Page → Save. Edit or remove: hover a tab's ⋯ menu → Edit page or Remove page.

Access is determined by Starhive, not Jira — only project members with access to that Starhive site see the tab; project admins see every tab, including ones marked (no access), so they can still edit or remove them.

Using it in Jira

Everyone interacting with a Starhive custom field or page consents to data sharing between the app and Starhive on first use (a standard consent button).

On an issue: each selected object shows its label and avatar; an info button (ⓘ) reveals its full attribute detail. Typing to search runs a query roughly equivalent to @Label * <input> combined with the field's configured query.

Filtering issues by JQL:

"Starhive custom field" ~ Cow

Renaming an object's label in Starhive doesn't retroactively update the label already stored on existing issues — only updating the field on those issues does.

Filtering with StarQL in JQL — the starQL function takes a query and a field name/ID:

issue in starQL("@Label * StarQL", "Component")
issue in starQL("@Label = Dog", "cf[10114]")

Results cache for 7 days; to force a refresh, change the query in a way that's semantically equivalent but textually different (e.g. @Label = dog → @Label = Dog). Only Starhive objects are cached, not Jira issues — a new issue referencing an already-cached object appears immediately, but a brand-new Starhive object won't until the cache invalidates.

Via the REST API, a Starhive object custom field takes this shape:

{
  "properties": {
    "objects": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "objectId": {"type": "string"},
          "label": {"type": "string"}
        }
      }
    }
  }
}

curl --request POST \
  --url 'https://<your Jira instance>/rest/api/3/issue' \
  --user 'user@example.com:<API token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "fields": {
        "project": {"id": "10000"},
        "issuetype": {"id": "10001"},
        "summary": "Issue Created with Starhive for Jira custom field",
        "customfield_10067": {
            "objects": [
                {"objectId": "9211a93c-db9a-49a0-99da-64b243f6c7b3", "label": "Abomasnow"}
            ]
        }
    }
  }'

Permissions

Jira only ever stores the object's unique identifier. Every time a field is viewed, its full data is fetched fresh from Starhive, evaluated against the viewing user's Starhive permissions at that moment — if an object is deleted or access is revoked, the user sees an explanatory message instead. The same applies to embedded pages: Jira stores only the workspace/site/page selection, and the page itself loads from Starhive via a short-lived token, checked against the viewer's permissions on each load. No Starhive data is persisted inside Jira.

Setting up the custom field​

Starhive object field​

Starhive object cascade field​

Admin configuration (Manage apps)​

Embedding Starhive pages in a project​

Using it in Jira​

Permissions​