RFCs are a way for Atlassian to share what we’re working on with our valued developer community.
It’s a document for building shared understanding of a topic. It expresses a technical solution, but can also communicate how it should be built or even document standards. The most important aspect of an RFC is that a written specification facilitates feedback and drives consensus. It is not a tool for approving or committing to ideas, but more so a collaborative practice to shape an idea and to find serious flaws early.
Please respect our community guidelines: keep it welcoming and safe by commenting on the idea not the people (especially the author); keep it tidy by keeping on topic; empower the community by keeping comments constructive. Thanks!
Summary of Project:
This project is designed to provide customers with timely access to improvements, bug fixes, and patched security vulnerabilities for their installed apps. Meanwhile, any additional permissions or egress can be reviewed and approved by admins at their convenience.
- Publish: 4 Aug 2025
- Discuss: 22 Aug 2025
- Resolve: 29 Aug 2025
Problem
A significant portion of Atlassian’s customer base is currently using outdated app versions, leading to a fragmented installation landscape. Feedback indicates that the current way Forge uses versioning to control and release changes to apps is not suitable for all use cases.
Customers
- Discovery of updates: Customers report difficulties in discovering app updates, lack sufficient information about what has changed, and often receive no advance notification.
- What changed: Release notes are inconsistent or missing, and audit logs lack detail. This situation makes it difficult for admins to comprehend what they might be missing by not approving an update, or even what to look out for that might break their workflow.
- Managing changes: Enterprise customers want to manage changes to their user experience, but currently have little control over when and how app updates (including minor updates) are applied. There is also no option for customers to roll back to a previous stable version in case there are issues with the latest version.
Developers
- Hesitation to release major versions: App developers often hesitate to release new features that necessitate major version updates, primarily due to the challenges and costs associated with maintaining support for multiple app versions over an extended period. As a result, customers miss out on new features and security updates, making it difficult to implement critical patches across the board.
- Supporting old versions: Many customers don’t manually upgrade major versions, and as a result, app developers need to support old major versions indefinitely. While we now provide features like the ability to perform progressive rollouts and deploy changes to previous major versions, this may be a significant and unnecessary overhead for some developers who lack the resources to manage it. An approach that keeps installations current would be a better fit.
Atlassian takes a different approach with its own cloud products, offering a model where customers don’t need to think about versions and are always presented with the latest released version. This is marketed as a feature of SaaS, removing the burden of version management from customers.
Moreover, app developers want more control over the experience their customers receive. Being able to immediately patch or make cost optimizations across all customers would provide significant value, particularly when responding to security events or when Forge monetization is introduced.
The Future of App Version Management
We envision a world where managing app versions is effortless, secure, and always up to date—without the headaches of manual updates or compatibility worries. Atlassian aims to redefine the app experience reducing the need for customers to manually manage versions and updates. With our vision, every app is current, secure, and tailored to your customers’ needs.
Here’s what it would look like:
- Always Up-to-Date, Effortlessly (Rolling Releases): No more chasing version numbers. Code updates are delivered automatically, ensuring apps are secure and high-performing, without disruption.
- Total Control, Zero Hassle (Optional Features): Admins get granular control to approve new features (a group of permissions), while routine updates flow seamlessly in the background.
- Ultimate Flexibility (Release Tracks): Customers will be able to set their own update policies, pre-approve features, and schedule updates to fit their business (similar to Release Tracks)—while still benefiting from protection against urgent threats.
- Crystal-Clear Communication: Customers will receive notifications only when it matters—like new features or permission change based on preferences. Customers will never be overwhelmed, but always informed.
- Full Transparency (Release Notes): Customers will enjoy complete visibility into the app update history, release notes and permission changes, empowering them to make informed decisions.
- Security and Compliance, Guaranteed: Outdated or insecure apps are shortlisted for review and critical security updates are enforced to keep customers’ environment safe.
- Developer Controlled Versioning (Semantic versions): Developers would have more control over version numbers, allowing developers to more clearly communicate the significance of the changes. eg. major version bumps when it is a workflow-breaking change.
Taking an iterative approach
We recognise that this is a complex challenge necessitating substantial investment to significantly enhance the experience for both customers and partners. We will adopt an iterative approach, with the first milestone focusing on decoupling versions from permissions. This will tackle the top reasons that major app versions are created: scope, egress and remote changes, reducing the amount of installations on older versions, in turn reducing the amount of outdated major versions that need support.
While this iteration represents a positive advancement, we acknowledge that it alone will not completely address the issues associated with app updates. We encourage you to assess this solution within the framework of our broader, ongoing investment, understanding that Atlassian is dedicated to continuous improvement in this domain.
Decoupling App Code Version from Consent
Separating the consent admins provide for app permissions (Initially, scopes, egress and remotes) from app code versioning (specifically updates, initial installations would still require all current permissions to be granted, and all permissions will need to be agreed to at once, an admin cannot opt out of a single specific permission), it would enable app developers to deploy updates to their apps without the current concerns they have today for triggering a major version upgrade for their customers and often increasing the amount of versions to support. After the changes are deployed, all installations that only have scope and egress changes (no matter how far back in Major version history) will be brought forward to the latest applicable version with no intervention from the Customer (Similar to the bulk-upgrade command).
App developers would instead need to develop their apps in a way to handle these permissions potentially not being available. This is a common pattern we see in other development frameworks, particularly in mobile app development with iOS and Android. These frameworks encourage developers to check for permissions (like camera, location, contacts, etc.) at runtime and gracefully handle the case where the permission is denied. This is inline with the direction we are proposing here for Forge app development.
Non-permission related major version changes
The process for releasing non permission related changes, changes to licensing would remain unchanged for this milestone and would still required admin approval before it would be released to customers.
Atlassian API security enforcement
Apps will still be restricted to only accessing Atlassian APIs which an Admin has granted permissions to, which may be different to the permissions defined in the manifest before an Admin has approved the new permission.
Surface app permissions to apps at runtime
To support these changes, we are proposing adding support for increased visibility of granted app permissions to apps at runtime. This would enable apps to pre-determine if an API call would be successful and provide an alternative experience within their app if it’s not available. We would be expanding on the API from the previous RFC RFC-94: Configurable Egress and Remotes to allow checks for scopes, non-configurable egress, and remotes as well.
Backend example (Non-final, illustrative only)
import { permissions } from '@forge/api';
const requiredPermissions = {
scopes: ['write:confluence-content'],
external: {
fetch: {
backend: ['https://a.com', 'https://b.com'],
client: ['https://test.com']
}
}
};
const result = permissions.hasPermission(requiredPermissions);
if (result.granted) {
// All permissions available - proceed with operation
console.log('✅ All permissions granted');
} else {
// Handle missing permissions
console.log('❌ Missing permissions:', result.missing.format());
// Output: "Scopes: write:confluence-content; External: Fetch Backend: https://api.example.com"
}
Frontend hook example (Non-final, illustrative only)
const MyComponent: React.FC = () => {
const { hasPermission, isLoading, missingPermissions } = usePermissions({
scopes: ['write:confluence-content'],
external: {
fetch: {
frontend: ['https://api.example.com']
}
}
});
if (isLoading) return <LoadingSpinner />;
if (!hasPermission) {
return <PermissionDenied missingPermissions={missingPermissions} />;
}
return <ProtectedFeature />;
};
Frontend render-props example (non-final, illustrative only)
<PermissionGate
requiredPermissions={{
scopes: ['admin:confluence']
}}
>
{({ hasPermission, isLoading, missingPermissions }) => {
if (isLoading) return <LoadingSpinner />;
if (!hasPermission) return <AdminRequired missingPermissions={missingPermissions} />;
return <AdminPanel />;
}}
</PermissionGate>
We believe this design will allow the developer to:
- Minimum permission check: Put a single bulk-permission check for all required permissions at the root of their app (like illustrated above) and show a message to the user that the app needs more permissions to function.
- Feature based: The developer could put this wrapper around individual features to disable them and tease them if they do not have the permissions needed to work yet.
Test migrating from previous major versions
As a result of this change some customers may automatically begin interacting with new versions of apps multiple versions ahead of what they were previously using. To support developers testing these migration paths on their apps, we are proposing to provide developers with a new command in the CLI to target installation of previous major versions.
Asks
We appreciate your engagement and look for feedback on this RFC that will help shape this offering.
Specifically, the Forge team would love to get some insights on:
- What use-cases for your apps that this offering would enable?
- This solution will initially be opt-in (for app developers), with the objective of becoming mandatory for all applications. What do you consider to be a realistic notice period before it becomes mandatory?
- How can Atlassian support app developers in educating customers about the new model to minimize confusion and ease the transition?
- What tools or features could Atlassian provide to give enterprise customers more control over app updates, especially since updates will be applied as new versions are available, without admin intervention?
- What support can Atlassian provide to help developers manage the overhead of ensuring decoupling versions from permissions won’t break the experience for customers running outdated versions?
Risks
- While the understanding of versioning by customers is mixed at best, the concept of major and minor versions for app installations is relatively clear within Atlassian R&D teams and support. During this transition, it may create some confusion and overhead to adjust to this new concept.
- Once an app is opted-into this feature, App updates will be deployed immediately to all customers by eligibility of the installed version vs the latest, regardless of how far back they are. Enterprise clients prefer to manage modifications to their user experience in a manner analogous to how they oversee parent product releases. Release Tracks are not presently supported for Marketplace apps, and once versions are decoupled from permissions, the risk of disruptive, frequent changes to the app user experience will escalate.
