Before releasing your first Forge version, compare its manifest with the Connect descriptor currently installed by your customers. This helps you to understand if your Forge version requires additional permissions that admins would need to manually approve. Run this command:
1 2 3 4 5npx @atlassian/connect-to-forge@latest check-upgrade \ --type jira \ --descriptor path/to/atlassian-connect.json \ --manifest path/to/manifest.yml
Use --type confluence for Confluence apps, or --type jira for Jira apps. To download a publicly hosted descriptor, replace --descriptor with --url https://example.com/atlassian-connect.json.
A missing or mismatched app key is a validation error: the command stops before checking permissions and exits with code 2. Otherwise, the command lists scopes that require admin approval. It also checks Connect backend URL changes, licensing, user-access mode, authentication providers and analytics egress. The report separates the product's automatic-migration checks from deployment restrictions.
All target scopes are checked; scopes missing from the product's scope map are treated as an escalation unless they are exempt or already granted.
Ordinary egress, additional remotes and regional remote edits are allowed. Analytics egress that introduces in-scope end-user data requires approval. Set inScopeEUD: false only if the analytics egress does not carry this data; omitting the property defaults to true.
A passing result is an automatic-migration candidate. This check assesses your app files. Automatic rollout also depends on installation eligibility and Atlassian’s rollout schedule. User-access mode prevents automatic migration even when scopes are equivalent. This command assesses only the initial Connect-to-Forge migration; Forge-to-Forge bulk-upgrade eligibility is outside its scope.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16CHECK STATUS WHY read:app-data:confluence ✔ OK – read:group:confluence ✔ OK – read:label:confluence ✔ OK – storage:app ✔ OK – write:app-data:confluence ✔ OK – write:label:confluence ✔ OK – write:page:confluence ✔ OK – Licensing ✔ OK unchanged User access ✔ OK – Egress ✔ OK – Remotes ✔ OK – Upgrade path ▸ automatic migration candidate Exit code ▸ 0 Note: This check assesses your app files. Automatic rollout also depends on installation eligibility and Atlassian’s rollout schedule.
If the check fails, the tool tells you which permissions might cause a problem.
1 2 3 4 5 6 7 8 9 10 11 12 13CHECK STATUS WHY delete:project:jira ✖ BLOCKS Requires Connect ADMIN, which the old descriptor does not grant (including inheritance). read:app-system-token ✔ OK – read:jira-user ✔ OK – Licensing ✔ OK unchanged User access ✔ OK – Egress ✔ OK – Remotes ✔ OK – Upgrade path ▸ admin approval required Exit code ▸ 0 Note: This check assesses your app files. Automatic rollout also depends on installation eligibility and Atlassian’s rollout schedule.
Use --json for machine-readable results and --strict to exit with code 1 when approval is required. Invalid inputs or unresolved comparisons produce exit code 2. Without --strict, a completed assessment exits with code 0 even when approval is required.
This check uses the supplied descriptor as the accepted installation baseline and applies to the first Connect-to-Forge migration. It does not query live feature gates or installation state. See Minor version updates for background guidance.
For more information on Connect and Forge permissions, view the list of Connect and Forge OAuth 2.0 scope equivalences.
Rate this page: