Atlassian Forge — Deep Research Guide

01 · Decision context

Forge is an application platform, not merely a serverless extension API

Forge combines Atlassian product extension points, hosted interfaces, managed Node.js compute, storage, events, queues, realtime messaging, remote-service integration, Rovo modules, Teamwork Graph connectors, and an evolving AI runtime.

1 Primary control plane manifest.yml declares modules, functions, resources, permissions, storage integrations, remotes, and AI capabilities.

3 Standard environments Development, staging, and production provide a managed promotion path with isolated variables and installations.

5 Major AI patterns Forge LLMs, Rovo agents, Rovo actions, contextual Rovo invocation, and Teamwork Graph connectors.

Best default boundary Keep UI, user authorization, Atlassian API calls, workflow orchestration, and ordinary application storage inside Forge. Use a remote service for proprietary systems, unsupported runtimes, specialized models, large-scale compute, vector infrastructure, or cross-platform orchestration.

S1 · Getting started S2 · Modules

02 · Platform architecture

The operating model

A Forge application binds an Atlassian extension point to a hosted interface or function. Forge supplies installation context, product APIs, identity-aware calls, storage, eventing, and managed execution.

The product module determines where an application appears and which contextual fields Forge supplies. UI and backend code are deployed together, while installations bind a deployed version to a specific Atlassian site and product.

S1 · Forge overview S2 · Manifest modules

03 · Product placement

Where Forge applications appear

Forge usually extends an existing Atlassian surface. The extension point is a product-specific module, not a generic route to an independently hosted website.

Product	Representative experiences	Good AI use cases
Jira	Issue panels, issue actions, project pages, dashboards, custom fields, workflow validators, UI modifications	Issue intelligence, dependency analysis, risk classification, release-note drafting
Confluence	Macros, content actions, space pages, global pages, configuration interfaces	Page synthesis, knowledge-gap analysis, document comparison, architecture assistance
Jira Service Management	Portal panels, request views, queue integrations, Assets imports	Request classification, suggested routing, response drafting, incident synthesis
Bitbucket	Repository pages, pull-request interfaces, events, merge checks	Change explanation, policy checks, review augmentation, repository intelligence
Rovo	Agents, actions, contextual chat initiation	Conversational discovery, guided workflows, bounded tool execution
Teamwork Graph	Third-party object ingestion and graph-aware retrieval	Enterprise search augmentation, cross-system knowledge, ownership and lineage

Design implication Start with the user’s Atlassian workflow and select the module that fits it. Do not start by choosing UI Kit or Custom UI. Product placement is the first architecture decision.

S2 · Module reference

04 · Experience architecture

Choose UI Kit for native workflows; Custom UI for richer applications

The UI decision is a trade-off between native integration and frontend freedom.

UI Kit

React-based components rendered through Atlassian’s supported interface model. It reduces frontend infrastructure and aligns strongly with Jira and Confluence behavior.

Use it for

Issue panelsFormsConfigurationWorkflow controlsSmall dashboards

Trade-offs

It is not an unrestricted browser DOM. Components that depend on direct DOM manipulation or unsupported browser behavior may not work normally.

Custom UI

A conventional HTML, CSS, and JavaScript application hosted by Forge and rendered inside an isolated iframe. It communicates with Forge through @forge/bridge.

Use it for

Complex chartsGraph explorersRich editorsAI workbenchesChat interfaces

Trade-offs

You own more accessibility, design-system consistency, dependency governance, browser security, layout, and client-side state management.

Requirement	Recommended implementation
Native Jira panel	UI Kit
Configuration form	UI Kit
Interactive lineage or dependency graph	Custom UI
Background automation	Function or event module; no UI required
Conversational experience	Rovo Agent
Native shell with a rich embedded area	UI Kit with Frame, or Custom UI

S3 · UI Kit S4 · Custom UI

05 · Developer workflow

Build locally with the Forge CLI

Atlassian documents current support for Node.js LTS releases, including Node.js 22 and 24. Standardizing new development on Node.js 24 reduces near-term runtime churn unless a dependency blocks adoption.

Install the runtime and CLI

Use a supported Node.js release and install @forge/cli globally.

Authenticate

Use an Atlassian account and API token with forge login.

Create from the nearest template

Select the target product and extension module. The template establishes a valid manifest and project structure.

Lint, deploy, and install

The application must be deployed before it can be installed on a development site.

# Install and select Node.js 24
nvm install 24
nvm use 24

# Install Forge CLI
npm install --global @forge/cli

# Authenticate and verify
forge login
forge --version

# Create an application
forge create
cd my-forge-app
npm install
forge lint
forge deploy

Representative project structure

my-forge-app/
├── manifest.yml
├── package.json
├── tsconfig.json
├── src/
│   ├── frontend/
│   │   └── index.tsx
│   ├── resolvers/
│   │   └── index.ts
│   ├── actions/
│   │   └── index.ts
│   └── consumers/
│       └── index.ts
└── static/
    └── app/
        ├── package.json
        └── src/

S1 · Getting started S5 · Node.js runtime

06 · Application control plane

Treat the manifest as an architectural contract

manifest.yml defines product placement, function handlers, resources, queues, remotes, permissions, runtime configuration, and AI facilities. It is both build configuration and a reviewable security boundary.

modules:
  jira:issuePanel:
    - key: issue-intelligence-panel
      resource: main
      resolver:
        function: resolver
      render: native
      title: Issue intelligence

  function:
    - key: resolver
      handler: src/resolvers/index.handler

    - key: analysis-consumer
      handler: src/consumers/index.handler
      timeoutSeconds: 900

  consumer:
    - key: analysis-queue-consumer
      queue: analysis-queue
      function: analysis-consumer

  llm:
    - key: app-llm
      model:
        - claude

resources:
  - key: main
    path: src/frontend/index.tsx

permissions:
  scopes:
    - read:jira-work

app:
  runtime:
    name: nodejs24.x
  id: ari:cloud:ecosystem::app/your-app-id

Versioning consequence Adding or materially changing permissions and capabilities can produce a new major app version and require an administrator to approve an upgrade. Manifest review belongs in architecture, security, and release governance.

Recommended manifest review checklist

Confirm the module is the smallest extension point that meets the workflow. Verify every scope is necessary. Review all external egress. Check function timeouts and queue usage. Validate remote endpoints, AI declarations, content-security permissions, and environment assumptions. Confirm that permission changes have an administrator-upgrade plan.

S2 · Manifest modules S6 · Deploy/version behavior

07 · Development feedback loop

Tunnel locally; validate with real deployments

Forge tunneling routes invocations from the development installation to local code. It accelerates iteration, but staging and production testing should use deployed artifacts.

# Route development invocations to the local machine
forge tunnel

# Inspect environment logs
forge logs --environment development
forge logs --environment staging
forge logs --environment production

Observability surfaces

Developer Console

Applications, environments, deployments, installations, logs, invocation metrics, API metrics, SQL metrics, custom metrics, usage, costs, alerts, and rollout status.

External observability

Export application telemetry into enterprise tooling. Normalize operation names, outcomes, model usage, queue delay, and bounded correlation identifiers.

Structured logging example

{
  "operation": "issue-analysis",
  "tenantHash": "non-reversible-value",
  "issueKey": "NBA-123",
  "jobId": "job-...",
  "model": "resolved-at-runtime",
  "inputTokens": 1430,
  "outputTokens": 380,
  "durationMs": 2180,
  "outcome": "success"
}

Do not log sensitive payloads Avoid access tokens, prompts containing confidential content, raw user-generated content, personal information, and unredacted model context. Log bounded metadata and non-reversible correlation values instead.

S7 · Tunneling S1 · Console and metrics S18 · Shared responsibility

08 · Release engineering

Promote one built artifact through development, staging, and production

Forge provides three standard environments. Each has independent deployments, variables, and installations. Custom development environments can isolate contributors or branches.

# Build once
forge build --tag "$GIT_COMMIT"

# Promote the exact bundle
forge deploy --tag "$GIT_COMMIT" --environment staging
forge deploy --tag "$GIT_COMMIT" --environment production

Environment-specific configuration

forge variables set API_BASE_URL "https://service.example"
forge variables set --encrypt API_TOKEN "secret-value"

forge variables set \
  --environment staging \
  API_BASE_URL "https://staging.service.example"

Information type	Recommended location
Nonsecret environment configuration	Forge variables
API token or client secret	Encrypted Forge variable
Per-installation secret	Forge secret storage
User preference	KVS or entity store
Relational domain data	Forge SQL
Large binary content	Object Store where acceptable, or external storage

S6 · Deploy CLI

09 · Consumption and distribution

“View” means user experience, developer operations, and distribution

End-user view

Navigate to the product context corresponding to the manifest module. An issue panel appears on an issue. A Confluence macro appears in the macro browser. A Rovo agent appears in Rovo when the app and Rovo are available.

Developer view

Use the Developer Console and CLI to inspect installations, deployments, environment variables, logs, metrics, storage, costs, and rollout state.

Private distribution

Deploy to production, enable application sharing, create an installation link, and provide it to the target Atlassian administrator.

Public distribution

Publish through the Atlassian Marketplace and manage commercial and developer-space requirements.

forge install list
forge deploy list
forge settings list
forge variables list
forge logs --environment production

S2 · Modules S8 · Distribution

10 · Compute, storage, and integration

Use the managed platform first; externalize by exception

Functions

Managed Node.js handlers for resolvers, events, actions, authorization checks, API calls, validation, and orchestration.

Async events

Queue long-running or failure-prone work. This is the preferred pattern for model calls, imports, and processing that should not block a UI invocation.

KVS and entity storage

Use for configuration, preferences, idempotency, job state, and indexed structured records that do not require relational SQL.

Forge SQL

Hosted MySQL-compatible storage, provisioned separately per application installation. Use portable SQL and account for Forge-specific limitations.

Object Store

A Preview capability for larger binary content. Isolate adoption behind an abstraction while product maturity evolves.

Forge Remote

Connect Forge to enterprise services, private APIs, specialized models, vector databases, unsupported runtimes, or high-scale compute.

Remote services expand the responsibility boundary Validate Forge invocation tokens. Isolate tenants. Protect Atlassian access tokens. Implement retries, timeouts, observability, regional controls, and data-residency behavior. External egress can affect eligibility for Runs on Atlassian.

S5 · Node.js runtime S9 · Async events S10 · Forge SQL S11 · Forge Remote

11 · AI experience design

Five distinct AI patterns

The patterns are complementary. A mature application may use a Rovo agent for discovery, Rovo actions for bounded operations, Forge LLMs for synthesis, async workers for long-running processing, and Teamwork Graph for enterprise knowledge.

1. Forge LLMs API

Atlassian-hosted model access through @forge/llm, including model discovery, chat, streaming, tool definitions, usage reporting, and error handling.

Best for: summarization, classification, requirement-gap analysis, document synthesis, and explanation of structured data.

Maturity: Preview. Apply adapters, budgets, feature flags, and lifecycle monitoring.

2. Rovo Agent

An AI teammate defined in the app manifest with a name, description, system prompt, conversation starters, and available actions.

Best for: issue analysts, incident assistants, architecture guides, release assistants, and service-desk copilots.

3. Rovo Actions

Typed, deterministic operations that map natural-language intent to a Forge function or remote endpoint.

Control: validate all arguments, reauthorize the operation, require confirmation for writes, and apply idempotency.

4. Contextual Rovo invocation

Use Forge Bridge to open Rovo Chat with a prefilled prompt and contextual intent.

Best for: “Analyze this issue,” “Explain this failure,” or “Compare these proposals” without implementing a complete chat interface.

5. Teamwork Graph connector

Normalize third-party objects and ingest them into Atlassian’s graph for graph-aware search and Rovo experiences.

Best for: API catalogs, ownership, repositories, incidents, AWS resources, architecture records, runbooks, and lineage.

External model gateway

Use a Forge Remote when you need models or infrastructure unavailable through Forge LLMs.

Best for: multimodal processing, private models, fine tuning, central policy enforcement, model routing, GraphRAG, or specialized safety controls.

Long-running AI interaction

Action control model

Action type	Default control	Required safeguards
Read-only retrieval	Normal user authorization	Validate arguments; minimize returned context
Create	Explicit confirmation	Reauthorize; validate fields; idempotency; audit
Update	Explicit confirmation	Validate state transition; concurrency check; audit
Delete	Strong confirmation	Permission verification; recovery path where possible; audit

S12 · Forge LLMs S13 · LLM pricing S14 · Rovo Agent S15 · Rovo Action S16 · Rovo Bridge S17 · Teamwork Graph

12 · Reference architecture

Enterprise AI architecture for Forge

This pattern keeps Atlassian context and authorization close to the Atlassian boundary while supporting specialized enterprise AI services when justified.

UI responsibility

Collect explicit intent. Expose what will be analyzed. Display progress and evidence. Require confirmation for writes. Provide retry and recovery states.

Resolver responsibility

Validate request shape. Recheck user authorization. Fetch only necessary Atlassian data. Build bounded context. Enqueue expensive work.

Worker responsibility

Redact unnecessary sensitive fields. Apply token budgets. Invoke the model. Validate structured output. Store provenance. Publish completion.

Action responsibility

Treat generated arguments as untrusted. Reauthorize. Validate transitions. Apply idempotency. Record an audit event. Return bounded output.

Metrics that make AI operable

Requests by use caseSuccess rateQueue delayModel latencyInput tokensOutput tokensCost by operationAcceptance rateRegeneration rateWrite confirmationsAuthorization failuresUnsupported-claim rate

13 · Security and tenant isolation

Managed infrastructure does not remove application responsibility

Forge manages much of the platform. The application remains responsible for authorization design, scope minimization, input validation, output encoding, secret management, logging hygiene, tenant isolation, retention, and dependency risk.

Identity-aware API calls

Use asUser() for operations performed on behalf of a user. Perform explicit authorization checks before privileged asApp() operations.

Least privilege

Request only required scopes. Scope additions are security changes and may create administrator-upgrade consequences.

Untrusted input

Validate user input, webhook data, model-produced arguments, and Rovo action parameters. The model is not an authorization system.

Secrets and logs

Use encrypted configuration. Never include access tokens, confidential prompts, personal information, or raw customer content in logs.

Cross-tenant leakage risk Forge may reuse Node.js runtime instances. Do not keep tenant data in module-level maps, arrays, caches, or singleton state unless the design provides rigorously verified partitioning and lifecycle controls.

// Unsafe: may outlive one invocation and one tenant context.
const tenantCache = new Map<string, unknown>();

AI-specific controls

Risk	Control
Prompt contains excessive customer data	Context minimization, field allowlists, redaction, token budgets
Model invents a write argument	Typed schema validation, server-side lookups, confirmation, authorization
Unsupported claim appears authoritative	Evidence links, confidence labeling, source-grounded output schema
Repeated write after retry	Idempotency keys and state-transition validation
Model or feature changes behavior	Versioned prompts, model discovery, regression evaluations, feature flags
External model changes data boundary	Central gateway, classification policy, residency review, explicit egress registry

S18 · Shared responsibility

14 · Product maturity

Separate core capabilities from Preview and EAP dependencies

Status can change. Verify the official documentation before production approval. Preview and EAP features should sit behind replaceable interfaces and explicit rollout controls.

Core platform

Node.js functions, UI Kit, Custom UI, async events, realtime, KVS/entity storage, Forge SQL, Forge Remote, and current Rovo modules.

Preview

Forge LLMs, rolling releases, application REST APIs, and Object Store were documented as Preview at the time of research.

Early Access

Global UI, Forge Containers, and Rovo Agent Connector were documented as EAP or experimental. Do not make them irreversible production dependencies.

Production rule Isolate Preview and EAP features behind adapters, capability checks, and feature flags. Define a fallback path before launch.

15 · Platform fit

Strengths and limitations

Strengths

Native access to Atlassian workflows and user context.
Managed authentication and product integration.
Hosted UI, compute, storage, queues, and events.
Strong fit for Jira, Confluence, JSM, and Rovo augmentation.
Tenant-aligned installation model.
Marketplace and private distribution paths.
Potential Runs on Atlassian eligibility.
Lower operational burden than a fully standalone integration platform.

Limitations

Experience placement depends on available product modules.
UI Kit is not a general browser DOM.
Custom UI executes in an iframe.
Function, payload, queue, invocation, and storage limits shape architecture.
Forge SQL is isolated per installation, complicating global analytics.
Permission changes can require administrator upgrades.
Rovo availability varies by tenant and product configuration.
High-value capabilities remain Preview or EAP.
Remotes reintroduce infrastructure, residency, and operational obligations.

Decision heuristic

Question	Forge-first signal	Remote-service signal
Where does the workflow live?	Inside Jira, Confluence, JSM, Bitbucket, or Rovo	Cross-product or independent application
What data is required?	Mostly Atlassian context and installation-local state	Many proprietary or cross-tenant enterprise sources
What compute is required?	Bounded functions and queue consumers	Large files, accelerators, custom runtime, sustained compute
What AI is required?	Supported Forge LLMs and bounded actions	Private models, multimodal, custom routing, vector or graph infrastructure
What compliance posture is desired?	Minimize external egress and infrastructure	Existing approved internal AI control plane

16 · Adoption roadmap

Start with evidence-linked read experiences, then add actions and enterprise knowledge

Phase 1 — Platform proof

Build a read-only Jira issue intelligence panel. Use UI Kit, Node.js 24, asUser(), Async Events, Forge LLMs, Realtime, and KVS job state. Measure latency, evidence quality, cost, and authorization correctness.

Phase 2 — Actionable workflow

Add a Rovo agent and typed actions. Keep read actions frictionless. Require explicit confirmation and idempotency for writes. Add structured audit records and an evaluation dataset.

Phase 3 — Enterprise knowledge

Add Teamwork Graph connectors for service ownership, API catalogs, architecture records, repositories, incidents, runbooks, and lineage.

Phase 4 — Platformization

Standardize TypeScript libraries, authorization middleware, context builders, AI output schemas, prompt registry, evaluation harness, cost controls, deployment pipelines, security review, and observability conventions.

Proof-of-value success criteria

P95 initiation < 1 second No unauthorized retrieval Every material claim linked to evidence Token and cost telemetry User usefulness rating Structured failure modes Documented fallback

Target platform split Forge owns Atlassian placement, user interaction, authorization, product-context retrieval, and workflow orchestration. Rovo owns conversational discovery. Teamwork Graph augments enterprise knowledge. Forge LLMs handles governed Atlassian-local generation. The core AI platform remains accessible through Forge Remote for specialized retrieval, models, policy, lineage, and cross-system orchestration.

17 · Provenance and audit

Source registry

The research is based primarily on official Atlassian developer documentation. Product maturity and limits can change. Revalidate Preview, EAP, pricing, runtime, and product-availability statements before implementation approval.

Methodology and limitations

The document synthesizes the platform model, current development workflow, deployment mechanics, product placement, AI capabilities, security responsibilities, and enterprise architecture implications. Sources are mapped at section level rather than footnoted after every sentence. Some recommendations are architectural analysis rather than Atlassian product claims.

Fact: capabilities, commands, APIs, and maturity labels attributed to Atlassian documentation. Analysis: recommended boundaries, adoption phases, controls, and architecture patterns. Uncertainty: Preview and EAP status, quotas, pricing, and availability are time-sensitive.

S1

Forge getting started

Platform overview, CLI workflow, environments, console, and developer entry points.

S2

Forge manifest module reference

Product extension modules and manifest-based application placement.

S3

UI Kit

React-based native Forge interface model and supported components.

S4

Custom UI and UI extension options

Hosted static resources, iframe model, and custom frontend integration.

S5

Node.js runtime

Managed runtime behavior and supported Node.js execution model.

S6

Forge deploy CLI

Deployment, environments, tags, versions, and promotion behavior.

S7

Forge tunneling

Local invocation routing and development feedback loop.

S8

Distribute Forge apps

Private sharing and public Marketplace distribution.

S9

Async Events API

Queues and consumers for asynchronous and longer-running work.

S10

Forge SQL

Hosted SQL model, installation isolation, compatibility, and limitations.

S11

Forge Remote essentials

External-service integration, invocation validation, and responsibility boundary.

S12

Forge LLMs API

Atlassian-hosted models, invocation model, streaming, and lifecycle status.

S13

Forge LLMs pricing

Token consumption and application-developer billing considerations.

S14

Rovo Agent module

Agent prompt, actions, starters, and product integration.

S15

Rovo Action module

Typed action declarations and function or remote handlers.

S16

Forge Bridge Rovo API

Programmatic contextual invocation of Rovo from Forge interfaces.

S17

Build a Teamwork Graph connector

Third-party object ingestion, normalization, fan-out, and retry patterns.

S18

Forge shared responsibility model

Authorization, tenant isolation, logging, secret handling, and developer security obligations.

S19

Forge MCP Server

AI-assisted development using current Forge documentation and guidance.

S20

Forge AI Plugin

Agent skills for scaffolding, review, security, debugging, and connector development.