Tunneling runs your app code locally on your machine via the Forge CLI and ngrok.
Tunnelling requires Docker installed and running on your machine. Get Docker and start it before using the tunnel command.
Forge tunnel uses ngrok to tunnel invocations. As ngrok does not support anonymous users, you need to set up your credentials before using tunnel command. If you don't have an ngrok account, sign up for one.
Once you have an ngrok account:
version: 2 log_level: debug region: us authtoken: <your-ngrok-authtoken>
You can start a tunnel for any app that has been deployed and installed on to a site. To start a tunnel for your app, run the following command in your CLI:
You'll see output similar to this:
Tunnel redirects requests you make to your local machine. This occurs for any Atlassian site where your app is installed in the specific development environment. You will not see requests from other users. Press Ctrl+C to cancel. Checking Docker image... 100% Your Docker image is up to date. Reloading code... === Running forge lint... No issues found. === Bundling code... App code bundled. === Snapshotting functions... No log output. App code reloaded. Listening for requests...
Messages logged to the console will look similar to this:
INFO 17:34:04.955 Count of objects in test array: 0
Tunneling also helps you debug your app in two ways:
When running with a UI kit app, any changes to your source code triggers a rebundle from the Forge CLI. Once the rebundling is completed successfully, you can see your changes by refreshing the page that your app is on.
When running with a custom UI app, the Forge CLI serves the content from the directories specified in each that's defined in your manifest. This means that if your static assets require rebundling, you need to bundle them before refreshing the page that your app is on. See here for more details on declarations for custom UI apps.
While lets you avoid redeploying your custom UI app to test changes, you have to manually bundle it for each change you make. To solve having to do this, popular tools, such as create-react-app can automatically reload your app each time you change the code. These tools usually host their own server on a specific port.
For example, running with starts a server at by default. The Forge CLI allows you to proxy tunnel requests to these servers, enabling features, such as hot-reloading while developing your custom UI apps.
To connect a server to , first identify the port that the server is hosted on. In the above example, the port would be . Then, add the following to your file, under the your server is hosting:
tunnel: port: <YOUR_PORT_HERE>
For example, a definition might look like this:
resources: - key: main path: static/hello-world/build tunnel: port: 3000
Once a port has been added to a resource definition, running causes the Forge CLI to bypass the directory, and instead proxy the request to .
You can then run , and start your server by running . You can then see the assets served by your local server by refreshing the page that your app is on. If your server supports hot-reloading, you no longer need to refresh the page to see updates when you make changes to the code.
When running with non-UI functions, such as custom UI resolvers and web triggers, any changes to your source code triggers a rebundle from the Forge CLI. Once that rebundling is completed successfully, you can see your changes reflected in the next invocation of the function.
The command accepts a flag that will allow you to perform remote debugging in Chrome's DevTools and will pause execution when a statement is found. The is a special statement that invokes any available debugging functionality, such as setting a breakpoint. The statement will be ignored if you're not tunnelling in mode.
When you run with the flag, you'll be prompted with a message similar to the following:
Chrome inspector URL (add "debugger;" statement to your app to pause): devtools://devtools/bundled/inspector.html?experiments=true&v8only=true&ws=127.0.0.1:8000
Opening the provided inspector URL, your app will now pause on any breakpoints you add in your code.
This is a great way to interactively debug your application within the context of the breakpoint.
The current runtime's version of the Forge tunnel uses Docker, which may cause issues.
Docker doesn't follow symlinks when creating a container to avoid potential inconsistencies. Therefore, you can't use symlinks in your app repository.
To work around this, install Yalc locally and add dependencies via before running or .
The command will get stuck in the step if you:
To work around this, disable the "Rosetta" setting on your Docker Desktop and restart your Docker daemon.
Rate this page: