Use the Forge CLI on a corporate network

Building and deploying Forge apps requires your local development environment to communicate with Atlassian services and upload your app artifacts to our hosted environment. Because of this, your local development environment will need Internet connectivity.

Corporate network environments often have additional restrictions on local administrative permissions, downloading artifacts from public package repositories, and connecting to external sites via an HTTP proxy or through a firewall's allow list. For developers who are building apps from within these environments, some additional configuration steps may be required in order for the CLI to run successfully.

Depending on your network environment, you may need to perform some or all of these additional configuration steps.

Configuring NPM to use a local repository

Some corporate networks prevent access to public package repositories. Instead, a local package mirror is used to host approved packages and manage the bill of materials for software dependencies.

Because the Forge CLI is built on Node.js, installing the Forge CLI requires access to the central NPM repository to download and install the Forge CLI dependencies.

If you need to use a local NPM repository, run the following command in your terminal:

1
2
npm config set registry ${yourRegistry}

Where ${yourRegistry} is the HTTP URL to your local NPM package repository.

Installing node-gyp

The Forge CLI has a dependency on a third-party package called node-gyp. Installing node-gyp is slightly more complex than installing regular Node.js packages because it has non-JavaScript dependencies including some components that may need to be provided by your operating system. In some situations, the Forge CLI installation process may attempt to dynamically retrieve node-gyp’s native platform dependencies from external repositories, which will fail if you are required to use a local NPM package mirror. Or, the node-gyp installation may fail because it tries to build itself from the source, but the right build tools are not installed in your local development environment.

In this scenario, you should instead install the pre-built `node-gyp`` dependencies for your operating system as described in the node-gyp instructions.

After you’ve completed this pre-installation, you should try to install the Forge CLI again.

Configuring the development environment to work with an HTTP proxy

If your network requires outbound connections using an HTTP proxy, you will need to provide the Forge CLI with details on your proxy server configuration.

If you are unsure, you may be working from a network with an HTTP proxy if you are seeing connectivity errors when trying to run commands with the Forge CLI. These could be SSL certificate errors, connection timeout errors, or connection reset errors. For example:

1
2
request to https://api.atlassian.com/graphql failed, reason: read ECONNRESET`

You will need to know the connection details of your proxy server. Contact your network administrator or IT team for this information if you are unsure.

Configuring NPM to use the proxy

NPM is the package manager for Node.js, which is used to download dependencies. By default, NPM downloads packages from the central NPM repository. Therefore, to install the Forge CLI, and the additional packages required for the CLI to work with a proxy, you also need to configure NPM to use your proxy configuration.

This can be done by running the following command in your terminal:

1
2
npm config set proxy ${yourProxyServer}

Replace ${yourProxyServer} with the HTTP URL of your proxy server. For example:

1
2
npm config set proxy http://proxy.example.com:8888

Configuring Forge CLI to use the proxy

The Forge CLI can be configured to work with a proxy server by modifying it to use the global-agent NPM package. This can be done by performing the following steps:

1. Install the package by running:

   1
   2
   npm install -g global-agent
   

2. Set the HTTP URL for connecting to your proxy as an environment variable by running:

   1
   2
   export GLOBAL_AGENT_HTTP_PROXY=${yourProxyServer}
   

3. Insert the following line of JavaScript to the third line of Forge’s cli.js:

   1
   2
   require('global-agent/bootstrap');
   

Allowing the Forge CLI to make outbound connections

If you are developing Forge apps from behind a corporate firewall, you may need to contact your network administrator to allow the CLI to connect to the external hosts it depends on. Below is a table showing which external hosts may need to be allow listed by your network administrator in order for the Forge CLI to function correctly.