Forge prerequisites | Enablement/Training resources by the Ecosystem Solution Architecture team

Forge
1

:waving_hand: before you join an enablement/training session with the Ecosystem Solution Architecture team (@tpettersen, @dmorrow, @ianRagudo and @CaterinaCurti), you should complete all the prerequisites on this post.

1. Forge prerequisites

Developer environment setup

Follow the instructions at Getting started with Forge to install one of the supported Node.js releases.

Forge CLI installation

Install the Forge CLI by following the instructions at Getting started with Forge.

Install the Forge CLI using npm. You’ll install the CLI globally so that the commands can be run across your system.

  1. Install the Forge CLI globally by running:
    npm install -g @forge/cli

  2. Verify that the CLI is installed correctly by running:
    forge --version

You should see a version number reported in the terminal. If a version number is not shown, then the installation failed. Repeat step 1 and look for errors reported in the terminal.

With the CLI installed, view the complete list of Forge commands by running forge --help.

Login with an Atlassian API token

Create or use an existing Atlassian API token to log in to the CLI. The CLI uses your token when running commands.

  1. Go to https://id.atlassian.com/manage/api-tokens.
  2. Click Create API token.
  3. Enter a label to describe your API token. For example, forge-api-token.
  4. Click Create.
  5. Click Copy to clipboard and close the dialog.

Log in to the Forge CLI to start using Forge commands.

NOTE: Do not use sudo or root user when running forge. Doing so may cause issues with file permissions and ownership, potentially leading Forge CLI not functioning properly when run by a non-privileged user.

  1. Start the process by running:
    forge login
  2. You’ll be asked whether to allow Forge to collect usage analytics data:
    Allow Forge to collect CLI usage and error reporting information?
    Answering Yes will allow Forge to collect data about your app’s deployments and installations (including error data). This, in turn, helps us monitor Forge’s overall performance and reliability. The collected data also helps us make better decisions on improving Forge’s feature set and performance. For information about how Atlassian collects and handles your data, read our Privacy Policy.
  3. Enter the email address associated with your Atlassian account.
  4. Enter your Atlassian API token. You copied this to the clipboard in step 5.

You will see a message similar to this confirming you are logged in:
✔ Logged in as Ian Ragudo

NOTE: The Forge CLI uses your operating system’s keychain to securely store your login details. Any command after forge login that requires authentication will read your credentials from the keychain. When this occurs, your keychain may prompt you for access; approve it to allow the CLI to run the command.

On Linux, you’ll need libsecret installed to perform this step.

Follow the first 2 Forge tutorials

To validate that all dependencies have been successfully installed and apps can be built, complete part 1 and part 2 of the Forge tutorials. Make sure to select the Jira App tab for each step:

In particular, confirm the correct execution of the following commands:

  • forge tunnel: Confirm that the app works when using forge tunnel command and that the logs are shown in the terminal. Some security tools might prevent the requests to be forwarded to the local workstation.
  • npm install @forge/api: not included in the tutorial as the package is already included in the template. However, we want to run this command to make sure we can install any required packages.

Troubleshooting tips & required outbound connections

In case of issues with the installation and usage of the CLI, review the Use the Forge CLI on a corporate network page. The page also contains the list of domains required for the outbound connections from the CLI.

Access to the developer.atlassian.com sites

Access to the developer documentation (https://developer.atlassian.com) and the developer console (Developer console) is required during the workshop.

Access to the developer community (The Atlassian Developer Community) might be useful as well for finding solutions and answers to common questions

Confirm access to the three sites.

2. Forge connectivity to behind-the-firewall systems

After identifying the systems the Forge app will need to integrate with, make sure we can connect to them.

This includes:

  • identifying the environment to connect to (e.g. integration testing / pre-prod instead of production)
  • make sure that the attendees have access to those systems (e.g. is UI access required? maybe to generate an API token?)
  • make sure that authentication options via JavaScript are known as well as any REST APIs required for the workshop
  • confirm access from a Forge app to these systems (e.g. by using https://developer.atlassian.com/platform/forge/runtime-reference/fetch-api.basic)

3. Sandbox / Development environment

If a sandbox is available to you, for development purposes it is recommended to use a Sandbox environment. Otherwise create a free cloud development environment.

Sandbox availability

A sandbox should be made available to the attendees and, at least one user can install apps on it via the forge install command.

Cloud Development environment availability

If a Sandbox is not available to you or you don’t have access to it, create a test site here.

4. IDE

Visual Studio Code (https://code.visualstudio.com/) is a popular JavaScript IDE to be used for Forge apps development.

If available, AI programming helper tools can also be useful when building apps.

5. Source code sharing method

If attendees from the same company are collaborating on the same app, it is recommended to setup a repository to host the code.

Feel free to leave any comments or questions here.

See you soon,
Caterina, Tim, Dugald and Ian