Ngrok agent < 3.1 no longer supported (affects out-of-box experience with ACE for non-paid ngrok plans)

Atlassian Developer Tools
,
1

Background

On November 30, 2023 ngrok announced that versions of the ngrok agent older than 3.1 would no longer be supported:

Free users of ngrok will experience service disruption if agents are not upgraded to at least version 3.2 by Jan 15, 2024

(Despite the blog post mentioning a date of Jan 15, 2024; it seems that older agents continued working past this date, and only started failing in the last couple of days, sometime around ~14 Feb, 2024.)

ACE + ngrok

Atlassian Connect Express provides guidance in the README under “Dev loop → Automatic registration” for installing ngrok as follows:

npm install --save-dev ngrok

The ngrok package on npm appears to be largely unmaintained. The last stable version, v4.3.3, was published in Aug 2022. This version supports (i.e. wraps) ngrok agent v2.x only.

There is a v5.0.0-beta.2 version of the package, that was published 9 months ago (May 2023); which appears to support ngrok agent v3.x. However the fact that it has remained a “beta” release with no other activity in the past 9 months does not inspire confidence.

It should be noted that there is an “official” Javascript ngrok wrapper, @ngrok/ngrok which does seem to be maintained. However the API differs from the ngrok package, which means that it is not a drop-in replacement. For example, ACE uses the following ngrok APIs:

ngrok.connect({ proto: 'http', addr: addon.config.port() });
ngrok.kill();


where as the equivalents in @ngrok/ngrok would be:

ngrok.forward({ proto: 'http', addr: addon.config.port() });
ngrok.disconnect();

Affect on Connect apps/developers

The ngrok deprecation of agents < 3.1 is not applicable to users that have a paid ngrok account; so it would seem that for any Marketplace vendors developing with atlassian-connect-express and wish to continue using ngrok for local development/auto-registration as per the guidance in the README has the following choices:

  1. Become a paid ngrok user; and continue using ACE with ngrok@4.3.3 (which wraps ngrok agent v2.3.40). Personal ngrok plans start at $10/month.
  2. Upgrade ther ACE projects to use ngrok@5.0.0-beta.2 (which wraps ngrok agent 3.x) and hope that it all works, given that it is still “beta software”
  3. Hope that the ACE team releases a version that supports @ngrok/ngrok instead of ngrok?

None of these options seem particularly ideal.

Can someone from Atlassian comment on what the plans are for ACE + ngrok going forward?

Thanks.

5 Likes
3

Thanks Scott, can you please submit a breaking change bug report ticket on behalf of everyone?

I’d bet Atlassian has no idea the single entrypoint into their development platform is currently broken.

Half my day wasted on this yesterday, and gave up before I could get anything to work.

4

Hey @scottohara,

Thanks for raising this, we’re actively looking into how we can update ACE to support ngrok/ngrok. In the interim, the other options which you have proposed are sound and can be utilised as a workaround.

We’ll provide further updates as things progress.

Cheers,
Sean

1 Like
5

Can you actually test for yourself and provide the community a guide here?

6

Apologies, this should have suggested ‘appear sound’ as we had not yet validated them.

7

A new version of Atlassian Connect Express (version 9.0.0) has now been published which implements @ngrok/ngrok. We recommending upgrading to this version if you are utilising automatic registration in ACE.

Please note that a new field ngrokToken is required in your credentials.json file to support this change, as detailed in the README.

4 Likes
8

Wow, thanks @SeanBourke !

I wasn’t expecting such a fast turnaround. We will give the new version a try over the coming days and report back if there are any issues.

9

Thanks, new ACE works :slight_smile:

2 Likes
10

@SeanBourke Is it possible to provide the ngrok token as an environment variable to not have it in source control? We have config.json in source control.

11

Thanks for the feedback @marc, I’ll explore it with the team. For now, we were looking for a pathway to immediately unblock this constraint in the ACE devloop.

@nathanwaters thanks for confirming everything is working on your end.

1 Like
12

For those that cannot update to the newest connect-express version: you can use ngrok - npm (Version 5.0.0-beta.2). This is a simple replacement of version 4.3.3 and supports ngrok version 3.1.1.

Or you can switch to a paid ngrok plan. Paid user are not forced to update their clients.

1 Like
13

The credential.sample you reference in the readme (Bitbucket) doesn’t reflect the ngrokToken option.

14

Hi @ThorstenKamann ,
This credentials sample file is for your Atlassian API key and email, to access your instance.

15

Curious question Sean, would you consider an option for https://zrok.io/? Its an open source alternative to Ngrok with a free SaaS. We have a Javascript/NodeJS SDK coming soon so no extra binary is needed inside ACE.

16

Install, Authorise and Configure ngrok

  • Sign up for an account: ngrok - Online in One Line
  • Obtain an auth token: ngrok - Online in One Line
  • Add it to a top-level field in credentials.json like this "ngrokToken": ""
    ACE will now read this file and automatically create an ngrok tunnel, and register your add-on on your development host.

I understand that the credentials.json has a new field named ‘ngrokToken’. Do we need this in the sample file, too?

17

If I understand correctly the field ngrokToken needs to be added to config.json, not credentials.json.

18

The excerpt i posted says credentials.json not config.json.

19

It seems I misread the information. I’ll try to delete/edit my earlier posts to not confuse others.

20

Hi @SeanBourke ,
No need to put environment variables into credentials.json. I was confused with config.json.

1 Like
21

Yo, can you guys stop changing things? This platform is an absolute nightmare to build on.

ACE v9.0.0 (yesterday):

"ngrokToken": "your_token"

ACE v10.0.0 (today):

"ngrok": {"authtoken": "your_token"}