Docs: Announce Forge-based GitLab for Jira Cloud app on Atlassian Marketplace
Problem to solve
The GitLab for Jira Cloud app documentation does not mention the migration from Atlassian Connect to Atlassian Forge. Customers who use the app from the Atlassian Marketplace need to know what to expect when the Forge-based version becomes available as a major upgrade.
Atlassian announced the end-of-support timeline for Connect apps. The Forge-based version of the GitLab for Jira Cloud app is being published to the Atlassian Marketplace as a major upgrade of the existing listing.
Affected documentation
-
doc/integration/jira/connect-app.md(rendered page)
Further details
Audience
Jira Cloud administrators and GitLab users who use the GitLab for Jira Cloud app from the Atlassian Marketplace. The information is relevant to users of GitLab.com and GitLab Self-Managed instances.
Key facts to communicate
These facts are confirmed by staging reviews in the gitlab-jira-forge project (#4, #6):
- Upgrade mechanism: The Forge version appears as a major upgrade requiring Jira admin approval.
-
Data preservation: Already-synced development data is automatically inherited because the Forge app uses the same app identifier (
gitlab-jira-connect-gitlab.com). - Feature parity: All existing features continue to work (branches, commits, merge requests, deployments, pipelines, feature flags, smart commits, branch creation from Jira).
- GitLab.com and Self-Managed: Tested with both GitLab.com and GitLab Self-Managed instances.
- No configuration changes required: Admins only need to approve the upgrade in Jira.
Proposal
Add a new section in doc/integration/jira/connect-app.md, after the "Update the GitLab for Jira Cloud app" section (## Update the GitLab for Jira Cloud app) and before "Security considerations" (## Security considerations).
Proposed content
The content below follows the GitLab documentation style guide, uses Hugo shortcodes for version history, and follows the page's existing structure and conventions.
## Migration from Atlassian Connect to Forge
{{</* history */>}}
- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/592890) in GitLab XX.X.
{{</* /history */>}}
The GitLab for Jira Cloud app has been migrated from
[Atlassian Connect](https://developer.atlassian.com/cloud/jira/platform/getting-started-with-connect/)
to [Atlassian Forge](https://developer.atlassian.com/platform/forge/).
This change follows Atlassian's
[end-of-support timeline for Connect apps](https://www.atlassian.com/blog/developer/announcing-connect-end-of-support-timeline-and-next-steps).
All existing features continue to work, including:
- Syncing branches, commits, merge requests, pipelines, deployments, and
feature flags to the Jira development panel.
- Creating GitLab branches from Jira issues.
- Smart Commits for time tracking and issue transitions.
- Support for both GitLab.com and GitLab Self-Managed instances.
### What to expect
If you installed the GitLab for Jira Cloud app from the
[Atlassian Marketplace](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud):
- The Forge version appears as a
[major upgrade](https://developer.atlassian.com/platform/marketplace/upgrading-and-versioning-cloud-apps/#changes-that-require-manual-customer-approval)
of the existing app.
- A Jira administrator must approve the upgrade.
- All previously synced development data is preserved automatically.
The Forge app uses the same app identifier, so no data migration is needed.
- No changes to your GitLab configuration are required.
For more information about the transition from Connect to Forge, see the
[Atlassian blog post on Connect end of support](https://www.atlassian.com/blog/developer/announcing-connect-end-of-support-timeline-and-next-steps)
and the
[Forge adoption guide](https://developer.atlassian.com/platform/adopting-forge-from-connect/how-to-adopt/).
Style notes
- Uses
{{</* history */>}}shortcode (not the legacy> Introducedblockquote syntax) - Does not duplicate
{{</* details */>}}(tier/offering) because the section inherits from the page-levelH1badge (Free, Premium, Ultimate/GitLab.com, GitLab Self-Managed, GitLab Dedicated) - Uses sentence case for headings
- Uses unordered lists (dashes) per style guide
- Keeps external links to a minimum and only to authoritative Atlassian sources
- Follows active voice and customer perspective
- Lines wrapped at approximately 100 characters
Who can address the issue
The Technical Writer assigned to the Plan stage, Project Management group. See assignments.
Other links/references
- Tracking issue: gitlab-jira-forge#7 (closed)
- Parent epic: &21004
- Forge app repository: https://gitlab.com/gitlab-org/gitlab-jira-forge
- Staging review (Ben King): gitlab-jira-forge#4 (closed)
- Staging review (Anton Smith): gitlab-jira-forge#6
- Atlassian Connect end-of-support: https://www.atlassian.com/blog/developer/announcing-connect-end-of-support-timeline-and-next-steps
- Forge migration guide: https://developer.atlassian.com/platform/adopting-forge-from-connect/how-to-adopt/
- Forge migration for custom apps: https://www.atlassian.com/blog/developer/connect-end-of-support-what-it-means-for-custom-apps-and-how-to-migrate-to-forge