Document must have at least 1 module (valid-module-required)

Forge Adopting Forge from Connect
1

I’m following the official guide for adopting Forge from Connect, which involves running npx connect-to-forge@latest to convert an existing Connect descriptor to an equivalent Forge Manifest.

(Put aside the fact that the above NPM package has since moved to @atlassian/connect-to-forge. The documentation for Forge and Connect-on-Forge in general is in much need of some attention. I have encountered many small paper cuts so far due to outdated or lacking documentation. For an initiative being pushed so heavily by Atlassian, the poor state of the docs just boggles the mind. Maybe someone from Atlassian who isn’t on the Forge team could go through this exercise and see for themselves?).

After running npx @atlassian/connect-to-forge@latest --type jira --url https://my.connect.app/atlassian-connect.json, the generated manifest.yml file includes this:

(For brevity, I’ve <redacted> large parts that aren’t necessary for this discussion)

app:
  id: ari:cloud:ecosystem::app/invalid-run-forge-register
  connect:
    key: <redacted>
    remote: connect
    authentication: jwt
  runtime:
    name: nodejs20.x
  licensing:
    enabled: true
remotes:
  - key: connect
    baseUrl: <redacted>
connectModules:
  jira:lifecycle:
    - key: lifecycle-events
      installed: /installed
  jira:jiraEntityProperties:
    <redacted>
  jira:dialogs:
    <redacted>
  jira:webItems:
    <redacted>
  jira:webPanels:
    <redacted>
permissions:
  scopes:
    - read:connect-jira
    - write:connect-jira
    - delete:connect-jira
modules: {}

Note the modules: {} at the end, which was added by the connect-to-forge tool.

The modules key is required, and this (correctly) shows that my Connect-on-Forge apps doesn’t yet have any Forge modules (only connectModules at this stage).

I successfully ran forge register, which updated the app.id with a proper identifier.

However, when I run forge lint (or forge deploy without the –-no-verify flag), I get the following error:

1:0     error    document must have at least 1 module  valid-module-required

What am I missing?

1 Like
2

Sorry to hear of your experience, Scott - if you can share the other documentation papercuts maybe I can fix at least some of those up for future readers.

Deleting modules will allow you to pass validation and deploy the app. I’m surprised we haven’t gotten more reports of this!

2 Likes
3

Thanks @jhazelwood .

re: documentation, here’s some quick ones off the top of my head:

  • As noted, references connect-to-forge@latest. Should be @atlassian/connect-to-forge@latest.
  • Mentions that “Your Forge app now has three environments by default: development, staging, and production, and each should have its own Connect key. There is no automated way (yet) of handling these.” (and links to an example deploy.js script as a possible workaround).
    I have seen community posts where people seem to be using manifest environment variables (e.g. key: ${APP_CONNECT_KEY}) - although it is unclear if that actuallyworks or not. If that is a viable approach, maybe mention it in the docs?
  • It would be good to understand the implications of NOT using different app.connect.key values across different environments.
    In our case, our Connect app uses one key and we deploy to different dev / staging / prod instances. Given that app.conect.key should match the Connect key in order properly take over the existing Connect app (and we would want to test this in dev & staging), it is somewhat unclear whether we do truly need different keys for each environment, or whether that’s just a suggestion?
  • The section that documents app.connect includes key and remote properties, but not authentication: jwt (which is part of the generated manifest that connect-to-forge produces).
    I couldn’t find anywhere that describes exactly what authentication: jwt means (but from community posts it seems like it just refers to how the connect app authenticates with the host product). It should be included in the manifest reference.
  • The page that documents permission.scopes doesn’t mention anything about Connect scopes (e.g. read:connect-jira, write:connect-jira etc.).
    Once again, community posts help understand what these are, but they should really be documented in the reference docs.
  • The connectModules section has no documentation at all. It just reads “A list of the Connect modules used by the app”.
    Its great that the connect-to-forge tool migrates these over, and looking at them it seems (for the most part) that these are are identical to how they’re defined in Connect, just represented as YAML instead of JSON. The exception is jira:lifecycle which, if it weren’t for the connect-to-forge tool, it is unclear where someone go to learn how to define lifecycle hooks for a Connect-on-Forge app? Maybe it is documented, but I couldn’t find it.
  • As mentioned, the section for modules in the reference indicates that this field is required; but as per your comment above, that doesn’t seem to be the case?

Another thing, that is technically not a documentation issue, but could perhaps be made a bit clearer is in relation to manifest variables, which I asked about here:

1 Like
4

This topic was automatically closed after 30 days. New replies are no longer allowed.