Checking your Forge adoption status

As you migrate your Connect app to Forge, your manifest.yml evolves to reflect how far along you are. The adoption-status command inspects your manifest and tells you exactly where you stand — whether you're just getting started, partially through the migration, or fully adopted.

Running the tool

You can run the tool directly from your Connect app directory without installing anything:

1
2
npx @atlassian/connect-to-forge@latest adoption-status

By default, the tool looks for a manifest.yml file in the current directory. If your manifest is elsewhere, use the --manifest flag:

1
2
npx @atlassian/connect-to-forge@latest adoption-status --manifest path/to/manifest.yml

Understanding the output

The tool checks your manifest for any remaining Connect artefacts and produces a summary of your adoption status.

Fully adopted

If your app has no remaining Connect modules or scopes, you'll see confirmation for each check followed by a summary:

1
2
✓ No Atlassian Connect modules found in connectModules
✓ app.connect.key is present
✓ No extra fields in app.connect beyond key
✓ No Atlassian Connect scopes in permissions.scopes

Adoption status: Your app is fully adopted on Forge. There are no remaining
Atlassian Connect modules or scopes in your manifest.

Partially adopted

If you still have Connect modules to migrate, the tool reports each issue with a suggested remediation:

1
2
✗ [E001] connectModules is present and non-empty (3 module types found)
          - jira:webPanels (2 modules)
          - jira:generalPages (1 module)
          - jira:lifecycle (1 module)
          → Migrate these to native Forge modules, or remove them if no longer needed.

Adoption status: Your app is partially adopted on Forge. Some modules have been
migrated to native Forge equivalents, but Atlassian Connect modules remain.
Resolve the errors above to complete your adoption.

3 error(s), 0 warning(s)

Not yet started

If you've registered on Forge but haven't migrated any modules yet, the tool will tell you that your app is functionally still a Connect app:

1
2
Adoption status: Your app has been registered on Forge but no modules or scopes
have been migrated yet. It is functionally still an Atlassian Connect app — all
of its behaviour is served by the Connect backend.

Gone too far

A common mistake is removing app.connect.key from the manifest when all Connect modules have been cleared. The tool specifically detects this scenario and explains that the key must be kept permanently — not that more migration work is needed:

1
2
✗ [E003] app.connect.key is absent
          → You have already fully migrated away from Atlassian Connect — but
            app.connect.key must be retained indefinitely as it ties the Forge
            app to its Connect identity. Add it back with your original Connect
            app key.

Adoption status: Your app appears to have gone too far — it looks fully migrated
to Forge, but app.connect.key has been removed. This key must be kept permanently.
Add it back to complete your adoption.

See The Connect and Forge dev loop for more detail on why app.connect.key must always be retained.

Warnings vs errors

The tool distinguishes between errors (things that must be resolved) and warnings (things worth being aware of but that don't block adoption). When all error checks pass, you'll see the four confirmation checkmarks — even if warnings are present.

Warnings don't block adoption — they highlight things like placeholder app IDs that should be addressed before publishing, or legacy URL patterns worth reviewing.

Using the tool in CI

Use the --strict flag to make the tool exit with a non-zero code if any errors are found. This lets you gate deployments or pull request checks on adoption status:

1
2
npx @atlassian/connect-to-forge@latest adoption-status --strict

Machine-readable output

Use the --json flag to get the full results as structured JSON, useful for integration with other tooling:

1
2
npx @atlassian/connect-to-forge@latest adoption-status --json