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

4 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

4 parts

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

Forge Gotchas

12 parts

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

Running a Forge app in production

4 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

TutorialAtlassian Forge

Make @forge/react/jira resolve, and keep forge deploy working

The types ship, your resolver cannot see them, and on a Forge app this is not an editor annoyance — the bundler type-checks, so it fails the build. Three TypeScript majors give three different errors, and only one setting is safe.

Sep 1, 20269 min read

ArticleAtlassian Forge

Atlassian is still health-checking the Connect app you migrated to Forge

Cloud Fortified monitoring is bound to app versions, not to your framework. Publish a Forge version and the probes keep hitting your old Connect base URL — each one carrying its own 99.9% SLO, and redirects are not followed.

Sep 1, 20267 min read

ArticleJiraAtlassian Forge

What LeanZero Management does that the other Jira PPM tools don't

A buffer task that absorbs slip until it can't, a plan that defends itself against edits made in Jira, and a write path that refuses rather than lies. Traced line by line, and set against what BigPicture and Structure.Gantt actually document.

Aug 31, 202618 min read

TutorialAtlassian ForgeSentinel Vault

I built a Forge major-version predictor on a guess, and it took a review to find the answer inside my own commit

Two triggers fired on the release that took us to 4.0.0, not one. I wrote a tool that knew about six of them when the docs list eleven, published a thesis that inverted the truth, and found the correct answer sitting in a comment in the same commit.

Aug 29, 202614 min read

TutorialAtlassian ForgeJira

Fix "Disallowing path manipulation attempt" from Forge's route tag, and know which of the two causes you hit

The @forge/api route template throws on two different mistakes with one identical message. Six steps to tell them apart and fix each, with a probe that prints exactly which characters it rejects in a path and which it silently encodes in a query.

Aug 27, 202611 min read

TutorialSentinel VaultAtlassian Forge

Refuse an unentitled caller in a Forge resolver, and prove it with a test that goes red without the gate

A Forge resolver that takes a page id from the payload and writes with asApp() will write to any page the caller can name. Six steps to gate it, with a test suite that fails 5 of 6 before the fix and passes 6 of 6 after.

Aug 27, 202615 min read

ArticleSentinel VaultAtlassian Forge

The duplicate Forge event that deleted our spam filter

Forge delivered one page edit twice, 400ms apart. The duplicate didn't post a second comment — it wiped the 24-hour window that stops second comments. Then I wrote the whole thing up backwards, and the test I built to prove it agreed with me.

Aug 27, 202613 min read

TutorialAtlassian ForgeJira

/rest/api/3/search is gone: what actually breaks when you swap in /search/jql

The removed Jira search endpoint fails loudly with a 410. The one-line migration to /search/jql fails quietly: HTTP 200, the right number of issues, and every field null. Measured from inside a deployed Forge app.

Aug 26, 202614 min read

ArticleCogniRunnerJira

CogniRunner 3.1.0: real Jira workflow conditions

For a year our workflow conditions evaluated a constant and gated nothing. 3.1.0 replaces that constant with ten checks that Jira runs itself. Here is what shipped, what I measured against a live Jira, and how it compares to what else is on the Marketplace.

Aug 24, 202617 min read

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