I spent October and November 2026 building Gherkin Studio, a BDD app for Jira Cloud, on Atlassian Forge. It lets a team write Gherkin scenarios inside a Jira story, syncs the .feature files both ways with GitHub, GitLab.com or Bitbucket Cloud, and shows CI results on each story. Atlassian approved it on the Marketplace on 18 November.
Forge runs your code on Atlassian's infrastructure, so there is no server to keep alive. It also has limits you only meet once real data arrives. These are the eight that cost me the most time, with the numbers I measured.
1. One storage value holds at most 240 KiB
Forge's key-value storage refuses any single value over 240 KiB. That sounds generous until you store a whole story's scenarios in one value, or an index of every step your team has written (for autocomplete), or a CI result for a story with hundreds of scenarios.
What I did: every place that writes a value now checks its size in bytes first, and my local test double of Forge storage refuses anything over 240 KiB, so the limit fails in tests instead of in production. The step index is capped by bytes, not by count.
2. A web trigger that takes too long gets a 424
CI pipelines post a Cucumber JSON report to a Forge web trigger. My first version checked each story in the report one after another. With 500 stories that took 56 seconds, and Forge stopped the trigger with HTTP 424.
Checking ten stories at a time (a small mapLimit helper, no library) brought the same 500 stories down to 6.7 seconds. Forge also refuses request bodies around 6 MB with a 413; 4.5 MB went through.
3. Slow work belongs in a queue, not in a resolver
The optional AI drafts call the Anthropic API. A short story took 16–20 seconds; a detailed one took more than 22, which is too long for a UI resolver. The call now runs in a Forge async event consumer with timeoutSeconds: 300, and the panel polls for the result. A long story takes about 40 seconds and nothing times out.
One trap: Forge retries an async event after an error or a timeout. Since the API call costs money, the job is marked as running before the paid call, so a retry does not pay twice.
4. Each Git host says "conflict" differently
Two-way sync means detecting when the file in Git changed since the last sync. The three hosts report a stale write in three ways:
- GitHub: 409 when the file's SHA is stale; 422 when the SHA is missing.
- GitLab: 400, with a message such as "changed since you started editing it".
- Bitbucket Cloud: 400, "The parent commit specified (…) is not the head of branch". Not 409.
All three answer 404 for a missing file, but also for a missing branch or repository. So before telling a user "the file was deleted in Git", the app tests the connection.
When both sides changed, nothing is overwritten. The app shows a line-by-line diff and the user picks Jira's version, Git's version or the text in the editor.
5. Jira can stop showing a module without an error
My status panel used jira:issueGlance. During review it simply stopped appearing on my test site, even with the old manifest. The docs now say the glance is replaced by the issue context module. Moving to jira:issueContext, with the same dynamic properties, brought it back under "Apps" on the story. I kept the glance for older views.
6. Deleting a story sends more events than the docs suggest
When an issue is deleted, the app removes that story's data in a trigger on avi:jira:deleted:issue. The docs say cascading events are not emitted, but a subtask deleted together with its parent did get its own event on my site. Deleting a whole project is a single avi:jira:deleted:project event, with no list of its issues.
7. Licensing exists only in production
context.license is only present in the production environment of a paid app. In development and staging it is undefined, so the code treats "undefined" as licensed and only "inactive" as read-only. You can test the inactive path by installing on a separate developer site with an inactive license.
8. The free compute is large
Forge includes 200,000 GB-seconds a month per app. A month of heavy testing on my site used 282. For a small app, compute cost is not the problem; storage limits and timeouts are.
What I would do again
- Fake Forge storage locally with the real limits, so tests fail where production would.
- Measure with real data before choosing a design. Every limit above showed up only with realistic sizes.
- Read what each Git host actually returns instead of what the docs imply.
If you build on Forge and hit something I missed, I'd like to hear it in the comments.
I'm the developer of Gherkin Studio, the app described here. It's on the Atlassian Marketplace, free for up to 10 users. This post first appeared on gherkinstudio.com.
