Topic hub

Atlassian Forge

Undocumented Forge platform behaviour, measured and worked around.

§01

What this covers

A one-line import at the top of a resolver file makes the whole resolver stop existing, and forge lint reports no issues. That is the shape of most of what is collected here.

Egress rules the backend ignores and the client enforces. Display conditions reading app properties nobody documented. A key-value store where FAIL_IF_EXISTS gives you a real lock and a TTL lease quietly does not. Each piece names the behaviour, shows the smallest thing that reproduces it, and gives the workaround that held up in production. Where Atlassian has since documented something, that is said. Where it is still undocumented, you get how it was confirmed, so you can check it yourself.

§02

Series

Read in order

Building CogniRunner

3 parts

What Jira workflow validators could not do, and what it took to put an LLM behind a transition without sending your data anywhere.

Building LeanZero Management

3 parts

Notes from building a Microsoft-Project-style planner inside Jira Cloud, on Forge, against limits that are not negotiable.

Forge Gotchas

5 parts

Undocumented Atlassian Forge behaviour that passes lint, passes deploy, and breaks anyway.

Running a Forge app in production

3 parts

The problems that only appear after deploy: testing against the live product, a security scan that passes wrongly, and rate limits counted in points.

§03

Everything on this topic

Articles

ArticleSentinel VaultConfluence

Sentinel Vault: you cannot block an edit in Confluence, so we undo it instead

Forge gives you no veto over a Confluence save. Product events arrive after the change is already committed, which means a lock on Confluence content cannot prevent anything — it can only detect and restore. Here is what that constraint does to an app: why the restore has to ignore itself, why reverting the whole page is the wrong fix, and why a licence check in a protection app must fail open.

Aug 19, 202611 min read

TutorialAtlassian ForgeLeanZero Management

LeanZero Management: virtualising a 5,300-issue Gantt

A 5,300-issue plan put 94,920 nodes in the DOM. Windowing the rows took it to 2,115 — and left a second full-height layer that windowing does not touch.

Aug 19, 202610 min read

TutorialAtlassian Forge

Locking in Forge KVS: FAIL_IF_EXISTS works, TTL leases do not

Forge does have an atomic create-if-absent, and it holds under concurrency. Add a TTL to turn it into a lease and it stops being one. Measured on a deployed app, with the manifest and code for the pattern that actually holds.

Aug 19, 202614 min read

TutorialAtlassian Forge

forge lint cannot see your request helper: the Jira scopes it never checks

forge deploy now blocks on lint errors, so the scope linter has quietly become a gate. It only reads endpoints written inline — one request helper hides every call in your codebase. Measured on @forge/cli 13.4.0, including what the runtime actually returns when a scope is missing.

Aug 17, 202614 min read

TutorialAtlassian ForgeLeanZero Management

LeanZero Management: two scheduling engines, one schedule

A Forge PPM app needs a live in-browser scheduler and a server-side one. They drift by a day, no test goes red, and the user believes the preview. Here is the harness that catches it — and the two mutations I ran to prove it works.

Aug 14, 202614 min read

TutorialCogniRunnerAtlassian Forge

jira:workflowCondition vs jira:workflowValidator: one runs your code

We shipped both modules in CogniRunner pointing at the same handler. Only one of them ever invoked it. forge lint says No issues found, forge deploy validates the manifest and passes, and the gate you built is permanently open with zero log lines. Here is the probe app that proves it, and the two things that actually work.

Aug 14, 202614 min read

ArticleAtlassian ForgeJira

LeanZero Management: the Jira dependency that actually moves dates

A blocks link in Jira records a relationship. On Free and Standard it reschedules nothing. Here's the engine we put behind it, the required-start rule that's easy to get subtly wrong, and what it still can't do.

Aug 13, 202612 min read

TutorialAtlassian Forge

Surviving Atlassian's points-based rate limits in a Forge app (2026)

Since March 2, 2026, a Forge app shares one 65,000-point hourly pool across every install. Ours spent it by 18 minutes past the hour. Here's the metering, the count tripwires and the self-imposed budget that took a 13,500-user Confluence estate down to ~2,000 points in a quiet hour — without a bigger quota.

Aug 12, 202611 min read

TutorialAtlassian Forge

jira:fullPage is deprecated: what global:fullPage actually changes for cross-product Forge apps

Atlassian gave Forge developers 55 days to move off jira:fullPage and confluence:fullPage. I built the cross-product app that fails today, reproduced the lint error verbatim, then migrated it to global:fullPage and deployed it into Jira and Confluence on one installation — and found that the context no longer tells you which product you are in.

Aug 11, 202614 min read

TutorialAtlassian Forge

Forge egress: backend ignores your URL path, client enforces it

The same URL in two Forge permission lists means two different things. I read the shipped matcher, deployed a probe to a live site, and measured which half of the docs is wrong.

Aug 8, 202614 min read

TutorialAtlassian Forge

The @forge/bridge import that kills your resolver, and why nothing warns you

One unused frontend import in a shared file takes a Forge function from HTTP 200 to HTTP 424. It throws at import time, the stack trace blames the wrong function, forge lint says No issues found, and the error message changed in April so the threads you'll find on Google no longer match.

Aug 4, 202613 min read

TutorialAtlassian Forge

Hide a Forge module per project: app properties in a display condition

Connect had entity_property_contains_any_user_group. Forge has no such named condition — but it can do the same job with a jiraExpression over your app's own properties. Here is the working manifest, the endpoint that actually exists, and the one-character bug that hides your module everywhere.

Aug 1, 202611 min read

TutorialAtlassian Forge

Security reports for Forge apps: the clean scan that isn't (2026)

Running SAST and SCA on a Forge app is easy. The hard part is that your scanner and the reviewer's will disagree about the same version, and if you don't explain why first, your report loses.

Jul 17, 202611 min read

TutorialAtlassian Forge

How to run real end-to-end UI tests against a deployed Forge app (2026)

Your Forge app's unit tests pass and it still breaks inside Jira. Here's how I drive a deployed Custom UI app in a real browser with Playwright — past the iframe and past Atlassian's 2FA.

Jul 15, 20269 min read

ArticleAtlassian ForgeAI Coding

What's New in CogniRunner: Local AI, Zero-Key Models & Actions That Write Back

CogniRunner's latest update brings local AI inference, a zero-key Atlassian-hosted model, and declarative AI actions that write back to Jira — all configured in plain English.

Jun 18, 20266 min read

TutorialCogniRunnerAtlassian Forge

Build an LLM-Powered Atlassian Forge App for Jira

A practical, end-to-end guide to wiring large language models into Jira workflows with Atlassian Forge — using CogniRunner as the real-world case study.

Jun 18, 202612 min read

ArticleAtlassian ForgeCogniRunner

The Gap Nobody Filled: AI-Powered Workflow Validation for Jira Cloud

Every workflow validator on the Atlassian Marketplace requires scripting. Every AI app for Jira is an assistant that can’t block a transition. CogniRunner sits in the gap between those two worlds — plain-English prompts that evaluate Jira field content, including attachments, as a real-time workflow gate.

Mar 16, 202610 min read

TutorialAtlassian Forge

Dark Mode Done Right in Forge Custom UI

Confluence supports dark mode. Your Forge app should too. This tutorial covers the full theme implementation for a production Custom UI app -- from Forge Bridge detection to a comprehensive CSS variable system that switches automatically.

Feb 18, 202615 min read