Admin & Settings

Overview

Site administrators can configure global settings for Sprint Reports & Stakeholder Updates from the Jira admin area.

Setting	Location
Admin page	Jira Administration → Apps → Sprint Reports & Stakeholder Updates Settings
What it controls	AI provider & API key, provider/model restrictions, default provider & model, rate limits, global field selection
Who can access	Jira site administrators

Permissions

The app uses Jira's built-in global permission system to control who can manage settings and who can generate reports. Permissions are configured at the site level and apply across all projects.

Permission	Default Grant	What It Controls
Manage Sprint Reports	Jira administrators	Save project settings, configure AI provider & model restrictions, manage API keys in the admin page
Generate Sprint Reports	All authenticated users	Generate, save, edit, delete, and publish reports to Confluence

How Permissions Work

• Read access is unrestricted — any project member can view settings, browse the archive, and read reports.
• Write actions are gated — saving settings requires Manage Sprint Reports; generating or deleting reports requires Generate Sprint Reports.
• Permissions are enforced both in the UI (buttons are disabled with an explanatory message) and on the server (resolvers reject unauthorized requests).

Customizing Permission Grants

Jira site administrators can change who has each permission through Jira’s administration UI:

1. Go to Jira Administration → System → Global permissions.
2. Find Manage Sprint Reports and Generate Sprint Reports in the list.
3. Add or remove Jira groups as needed. For example, restrict report generation to a “report-writers” group, or grant settings management to project leads.

The app also supports custom group mappings stored in Forge Storage, with a multi-level fallback: custom groups → Jira permission API → legacy admin check. This ensures permissions work reliably even if the Jira permission API is temporarily unavailable.

Built-in AI

The app ships with a built-in AI provider (Google Gemini 2.5 Flash) that works out of the box — no API key or configuration required. The built-in provider is automatically disabled when an organization API key is configured via BYOK.

Status Badge	Meaning
Active	Built-in AI is enabled and being used for generation. No organization key configured.
Disabled	An organization API key has been configured. The built-in provider is no longer in use.
Key not configured	No built-in provider available and no organization key has been set up. Generation will fail until a key is configured.

Bring Your Own Key (BYOK)

Site administrators can connect their organization's own AI provider instead of (or in addition to) the built-in Gemini provider:

1. Open the admin page (Jira Administration → Apps → Sprint Reports & Stakeholder Updates Settings).
2. Select a provider from the dropdown.
3. Enter the organization API key — it is stored encrypted in Forge's secret storage (never in plain text or Forge Storage).
4. Click Test Connection to verify the key works.
5. Click Save.

When an admin API key is configured, the built-in rate limit is bypassed. Projects select their preferred provider and model from the options the admin has enabled — they do not need their own API key.

Supported Providers

Provider	API Endpoint
Anthropic (Claude)	api.anthropic.com
OpenAI (GPT)	api.openai.com
Google Gemini	generativelanguage.googleapis.com
DeepSeek	api.deepseek.com
Mistral	api.mistral.ai
Qwen (Alibaba)	dashscope-intl.aliyuncs.com
Grok (xAI)	api.x.ai
Together / Llama	api.together.xyz
HuggingFace	api-inference.huggingface.co

Provider & Model Restrictions

Administrators can restrict which providers and models are available to projects:

• Allowed providers — a checkbox grid of the 9 supported providers. Only checked providers appear in project-level settings.
• Per-provider model restriction — for each allowed provider, choose which models are available: preset model checkboxes plus a free-text field for custom model IDs.

This follows an "admin ceiling" concept: project-level settings can only narrow the admin selection, never expand it. If an admin allows only Anthropic and OpenAI, no project can select Gemini or DeepSeek.

Default Provider & Model

The admin can set a default provider and model that new projects inherit automatically. Projects that have not explicitly chosen a provider will use this default. If no default is set, the built-in AI provider is used (when available).

Rate Limits

The built-in AI provider enforces a rate limit of 50 generations per day per installation. This counter resets daily at midnight UTC.

• The remaining generation count is visible to users in the Generator view.
• When the limit is reached, users see a message indicating the daily quota has been exhausted.
• Configuring an organization API key via BYOK bypasses the rate limit entirely — there is no daily cap when using your own key.

Field Selection

Control which Jira fields are included in AI report generation. The admin page sets the global default field selection that all projects inherit.

Built-in Fields

• Priority
• Status
• Labels
• Assignee
• Epic

Custom Jira Fields

In addition to built-in fields, administrators can enable custom Jira fields (e.g., Story Points, Sprint Goal, Team). Custom fields are resolved from the Jira instance and appear as toggles in the admin UI.

Project-level settings can narrow the global field selection (disable fields the admin enabled) but cannot expand it (enable fields the admin disabled). This ensures consistent data governance across the organization.

Project-Level Settings

Project administrators can configure per-project settings from the Settings tab within the app (project navigation bar → More → Sprint Reports & Stakeholder Updates → Settings):

Setting	Description
AI provider & model	Select from the providers and models the site admin has enabled.
Confluence space	Default Confluence space for publishing reports. Select a space and optionally set a parent page for each audience type (Board, Team, PO) to organize published reports. See Publishing to Confluence for details.
Custom fields	Narrow the global field selection for this project.
Default audience & tone	Pre-select the audience type and tone for new reports.
Report retention	How long archived reports are retained before cleanup.
OKR label	Jira label used to identify OKR-related issues for goal tracking in reports.

Credential Resolution

When generating a report, the app resolves which AI credentials to use in the following order:

1. Admin organization key — if a BYOK key is configured in the admin page, it is used. Rate limits are bypassed.
2. Built-in AI — if no organization key is set, the built-in Gemini provider is used (subject to the 50/day rate limit).
3. Error — if neither is available (built-in disabled and no key configured), the user sees an error prompting them to contact their site administrator.

Forge Permissions & Scopes

Sprint Reports & Stakeholder Updates requests the following Forge scopes during installation. These scopes define what data the app can access:

Scope	Purpose
read:jira-work	Read Jira issue data (summary, status, priority, assignee, labels) for report generation
read:board-scope:jira-software	Access board configuration and board-level data
read:sprint:jira-software	Read sprint data (name, dates, goals, state) for sprint reports
read:issue:jira-software	Read issues within sprints and boards
read:issue-details:jira	Read detailed issue fields including custom fields for enriched reports
read:jql:jira	Execute JQL queries to fetch sprint and version issues
read:project:jira	Read project metadata (name, key, boards) for project context
read:project-version:jira	Read Jira versions (Fix Versions) for release reports
read:user:jira	Look up user group memberships for permission checks
read:jira-user	Read user context for authentication and permission resolution
storage:app	Read/write Forge Storage (admin settings, report archive, project configuration)
report:personal-data	GDPR personal data reporting (weekly scheduled trigger)
write:confluence-content	Create and update Confluence pages when publishing reports
read:confluence-space.summary	List Confluence spaces for the space picker in publish flow
read:space:confluence	Read Confluence space metadata for publish target resolution
read:page:confluence	Read Confluence pages for linked document references
write:page:confluence	Write Confluence page content when publishing reports

The app also makes outbound API calls to the configured AI provider endpoint (see Supported Providers table above) for report generation. No other external network calls are made.

Need Help?

For questions or feedback, contact contact@be4.software or visit the support portal.