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:
Some partners who are looking to Adopt Forge from Connect have identified the need for a major update as a blocker. This RFC shares some of the exploration we’ve undertaken to assess how we could make the journey from Connect to Forge a seamless, minor update for apps which do not need to elevate their permissions.
For the purposes of this RFC, a major version/update reflects an admin-approved update and a minor version/update reflects a non-admin-approved update.
Please note that this RFC is not a commitment to all of the controls defined, but is rather seeking feedback to ensure have considered the needs of your apps. Once we have a confirmed and finalised set of guardrails, we will publish these to partners.
- Publish: 2024-10-17T13:00:00Z
- Discuss: 2024-10-31T13:00:00Z
- Resolve: 2024-11-14T13:00:00Z
Problem
As Connect apps move to Forge and start adopting Forge modules, they are required to add egress permissions, remotes and additional scopes. The addition of each of these properties results in a new Forge major version today. In addition to this, the first move from Connect to Forge is currently a major version update for all existing customers. The combination of these results in potentially multiple major version updates, requiring customers to approve the app’s update the first time it moves to Forge and each subsequent time it adds new Forge features.
Given customers may opt to not update their apps, partners are subsequently left in a position where active installations of their app are still loaded from their existing services. If that app opts to preference Forge capabilities, they will still be left in a position where they must either continue to maintain and deliver the previous Connect service, or they may need to switch off these services and manage the change/communication of a need to update to existing customers who have not yet updated.
Note: We appreciate that there are other challenges and constraints with app updates, however this RFC focuses wholly on the adoption of Forge from Connect and the implications of updates on that process.
Proposed Solution
Updating from Connect to Forge
This section details the considerations, constraints and approaches for handling the upgrade from the Connect version of the app to Forge version.
Scopes
Connect utilised implied scopes, where the declaration of DELETE would also inherit READ and WRITE scopes. Forge’s OAuth 2.0 scopes are declarative and each scope which is going to be utilised must be declared.
Where the Forge scopes (either classic or granular) are inheriting the same actions of the Connect scope via their expressed verbiage, that update would be deemed a minor update.
For example, a Connect app which had a WRITE scope declared would otherwise have both READ and WRITE in Connect via inheritance. This app could declare the following classic or granular scopes without incurring a major update (Note: this is not an exhaustive list, just an example):
read:jira-work(Classic Scope) - “Read Jira project and issue data, search for issues and objects associated with issues like attachments and worklogs.”write:issue:jira(Granular Scope) - “Create and update issues.”write:comment:jira(Granular Scope) - “Create and update issue comments.”
The same app would not however be able to adopt the following scopes, as they may elevate its permissions to actions which is aligned with a DELETE scope which the app did not previously have declared:
write:jira-work(Classic Scope) - “Create and edit issues in Jira, post comments as the user, create worklogs, and delete issues.”delete:issue:jira(Granular Scope) - “Delete issues.”
In a similar manner, if the Connect app were to declare an elevation of Connect scopes when moving from Connect to Forge, it would be deemed a major update. Only the Connect scopes which were previously present, a subset of them, or no Connect scopes would contribute towards an automated update.
The declaration of any additional Forge-specific scopes when moving from Connect to Forge will not be assessed as part of this upgrade and can be declared without any impact to version determination.
Our current mappings (which are subject to change) can be found here: Equivalent Connect to Forge OAuth2 Scope Mappings (Proposed)
Remotes, Content Permissions, Fetch Permissions and External Permissions
The addition or declaration of these properties will not have any bearing on an app’s version determination when upgrading from a Connect version to a Forge version.
Update Duration
Similar to the progressive rollout of Connect minor updates, these updates will be staggered over a period between 24 to 96 hours. During this duration, customers will still be provided with the ability to manually update their apps to the latest version.
Staged Migrations
We understand that some partners may want to stage the update process to test on their own sites to ensure that things are working as expected, or to reduce the rate of update requests. This update process will inherit similar controls to our current rollout, in which partners can request a staged migration.
Apps which have already moved from Connect to Forge
Connect to Forge updates are retrospective, in that they will compare the installed version of the Connect app with the latest version of the Forge app. Subsequently, once we have confirmed and finalised these guardrails, apps could move to Forge with confidence that customers on their existing major version would be automatically updated at a later date.
Where apps have already moved from Connect to Forge and have utilised Classic scopes where they otherwise required Granular scopes to align to the above requirement; they can deploy a new version of their Forge app and existing customers will be assessed against that version at their next scheduled check.
Updating on Forge
This section details the considerations, constraints and approaches for handling the upgrade of a Forge version of an app (potentially with Connect modules) to another Forge version.
Scopes
Where a Connect scope is still declared in the Forge app, it will inherit the scope considerations outlined in our current mappings when adopting a subsequent Forge scope while moving from Connect to Forge.
While we do not immediately plan to support a similar mechanism when adopting Granular Scopes to Classic Scopes, it is a consideration which we would appreciate feedback on. The following is a hypothetical example if we were to also implement this.
Forge’s OAuth 2.0 scopes come in two types - classic and granular. Where a newly declared Forge granular scope is inheriting the same actions of the classic scope via its expressed verbiage, that update would be deemed a minor update.
For example, a Forge app which had a write:jira-work could declare the following granular scopes without incurring a major update (Note: this is not an exhaustive list, just an example):
write:issue:jira- “Create and update issues.”write:comment:jira- “Create and update issue comments.”delete:issue:jira- “Delete issues.”
The same app would not however be able to adopt the following scopes, as they may elevate its permissions to actions which is aligned with a manage:jira-configuration scope which the app did not previously have declared:
write:project:jira- “Create and update projects.” (This is aligned tomanage:jira-configuration)
As long as no elevated scopes are present, the removal of any scopes would also be deemed a minor update of an app.
Remotes, Fetch Permissions and External Permissions
As Connect modules are inherently remote, if one or more Connect modules are present, the addition of new Remotes, Fetch Permissions or External Permissions will be reflected as a minor update . This reflects the opportunity to extend and replicate your existing front-end via Forge modules.
If a broader permission (i.e. ‘’ or '.domain.com’) is defined as a Fetch Permission or External Permission, the inclusion or modification to a domain which is a subset of the previously permitted permission to the same permission group will be reflected a minor update. This may be coupled with a requirement to remove the broader reaching permission.
Content Permissions
The introduction or inclusion of new content permissions will not invoke a new major version and will be reflected as a minor update.
Update Duration
Updates which result in changes to remotes, content permissions, fetch permissions and external permissions would be immediately reflected across all sites (similar to a minor update). Any updates which modify the scopes of an app would be progressively rolled-out over 24 - 96 hours to all sites.
Preflight Update Check
It can be difficult to distinguish when a change to your manifest will result in a major update - you must either familiarise yourself with the update criteria, or become aware following a deployment. A preflight capability enables developers to validate if a deployment will result in a major update prior to deploying their app.
Delivery Sequence
We are proposing that support for Forge minor updates are delivered prior to Connect to Forge minor updates; or that these are delivered concurrently.
As Forge minor updates do not provide retrospection, the delivery of Connect to Forge minor updates first would result in customers being updated from Connect to the first Forge version, then being stuck on that first Forge major version.
Corollary, by delivering Forge to Forge minor updates first, we ensure that any customers who install your new version or update from your previous Connect version will have a minor version pathway. Once Connect to Forge minor versions are made available, existing customers who had not yet updated would be caught up.
Example Adoption Pathways
Adoption before any milestones are delivered
Once we’ve published our finalised guardrails, apps can start to move with confidence , knowing that any installations on a previous Connect major version will be moved to Forge once the minor update capability is delivered. Any updates on Forge may still be major versions, however this will predominantly be seen by new customers, or those who have already updated from the previous Connect version.
Adoption once Forge minor updates are delivered
Similar to above, apps can have confidence in adopting early as previous Connect major versions will be assessed against the latest Forge version. This ensures that any changes in Forge would become minor versions, supporting new customers and those who have updated.
Adoption once all milestones are delivered
Once all milestones are delivered, customers will be updated from Connect to the first version of the Forge app delivered. Any subsequent updates would also be minor updates to a newer version of Forge.
Asks
While we would appreciate any reactions you have to this RFC (even if it’s simply giving it a supportive “Agree, no serious flaws”), we’re especially interested in learning more about:
- Do the scope mappings provided work for your current use cases? Are there any mappings which may result in you experiencing a major version update which seem unreasonable?
- Does our delivery sequence seem reasonable? Does the above proposal give you suitable confidence to start building (or even publish) a Connect to Forge app once we publish finalised guardrails? At which milestone do you believe you would feel comfortable releasing a Forge version of your app?
- Can you foresee any significant constraints if egress changes on Forge required an accompanied replacement (i.e. removal) of a Connect module?
- Some apps may have previous major versions based upon a change in their
apiVersion. Would you prefer these to also update as part of Connect to Forge, or would this result in breaking changes to your app? - Is there anything you believe we are missing, or which should be reconsidered in the above proposal?
)