Setup Documentation

Administrator Setup Guide

Follow this guide to configure Refinely for your Jira Cloud workspace. Refinely uses a Forge-hosted BYOK architecture so your team keeps control of provider selection and usage.

1. Installation

Refinely is a Forge-native app published on the Atlassian Marketplace. To install:

Log in to your Jira instance as a Jira Site Administrator.
Navigate to Apps → Find new apps.
Search for "Refinely" and click Get app.
Accept the permission scopes required for operation.

2. Procure AI Vendor Keys

Refinely doesn't include AI compute in its licensing. You must provide your own API credentials to maintain full data sovereignty and cost control.

OpenAI

Recommended — speed & versatility

Procure Key

Security Note: Expanded PII Masking

For applicable expanded-package workspaces, Refinely can mask supported PII patterns before data is sent to your AI provider. These controls are not included in the Standard Marketplace tier.

3. AI Execution Policies

Refinely lets admins choose the provider, model routing strategy, and discovery depth used for refinement workflows. These controls can be tuned without changing how end users work inside Jira.

Execution Preset

Execution controls determine how much clarification and model routing Refinely uses before generation. Start simple, then expand only if your team needs more control.

Locate the model strategy section.
Choose the setup mode that fits your team: Simple for lighter configuration or Advanced for deeper control.
Save the configuration so workspace defaults are applied.

Standard vs. Complex AI Model

Refinely can route different workflow stages to different model profiles. Admins decide which configured model is used for speed-focused vs. deeper-reasoning work.

In AI Setup, assign a provider and model to your core workflow buckets.
Use faster models for lightweight refinement and deeper models for ambiguous requirements.
Refresh the provider catalog when you add or change models.

4. Jira Field Mappings

Configure exactly where Refinely writes its AI-generated Acceptance Requirements (ARs).

Consolidated Mode

1. Select a target Jira project.
2. Choose a Destination Field (e.g. Description).
3. Toggle Overwrite or Append logic.

Iterative Mode

1. Select your target project.
2. Map GIVEN/WHEN/THEN to separate custom fields.
3. (Optional) Set child-issue linking type.

5. Work Instructions

Upload your organisation's process documents, SOPs, or standards guides. When a ticket relates to a documented process, Refinely retrieves the relevant sections and uses them as grounding context during generation.

How to Upload Work Instructions

Click Upload Document and select your file. Supported formats: PDF, Excel (.xlsx/.xls), CSV, Markdown (.md), plain text (.txt), and email (.eml).

Optionally scope the document to a specific Jira project key so it's only used for relevant tickets.

Refinely chunks and indexes the document automatically. During generation, it retrieves the most relevant sections — no manual copy-paste required.

6. Transparency & PII Controls

Expanded workspace controls

PII Masking, Audit Trails & Transparency Reports

Refinely can provide additional controls for teams that want more visibility into model usage. These controls can include automatic PII masking before outbound model calls, audit events, and transparency reports that show which context contributed to a generation.

These controls are not included in the Standard Marketplace tier. Contact support if you want help evaluating expanded packaging.

Contact support

Ready to Refine?

Once your Global Key is saved, the Refinely widget will appear on all Jira tickets. Your team can start generating high-density backlogs immediately.

Get Technical Support