Changelog

This changelog is the source of truth for all changes to the Forge platform that affect people developing Forge apps.

Post are made in the Forge Announcements category of the developer community when the changelog is updated. Subscribe to the Forge Announcements category to get notifications.

15 Oct 2020

added New useEffect hook

This is a late announcement that the useEffect hook was released in Forge UI version 0.6.0. See the related release notes for more details.

14 Oct 2020

updated User collection type for Jira custom field module

You can now use the user collection type with the jira:customField module. This enables a Jira custom field in your app to store a list of users.

12 Oct 2020

bug fixes in Forge CLI version 0.22.0

This release includes:

• forge lint now respects relative paths when using a custom tsconfig.json file.
• Streamlined reporting of fixable errors with forge lint.
• Additional manifest validation rules and improvements to some existing messages.

6 Oct 2020

notice - deprecation Developer-based app authentication

The previous asApp() developer-based authentication is deprecated and will be removed in a future release.

You need to upgrade all existing installations of your app before 23 November 2020; at which point, the previous developer-based authentication flow will be removed.

To upgrade your app, run the forge deploy command, and then run forge install --upgrade for every installation of your app. For more information, see upgrade the app.

added Improved app authentication

This release improves app authentication. Previously, the .asApp() function call was authenticated using the identity of the developer who installed the app.

With improved app authentication, a special user is provisioned for the app when it is installed. The app’s user identity is used for API calls when the .asApp() function call is used.

With an app user provisioned, developers are no longer asked to provide consent for the app to access their account during the forge install command.

The improved app authentication behavior applies by default to all new apps.

18 Sep 2020

bug fixes in Forge CLI version 0.21.1

This release includes:

• Added manifest validation for the jira:issueGlance module.
• A fix to manifest validation so it no longer requires for a function to be defined.
• A fix to prompt users to update app installation only for the environment that the app was deployed to.

Run npm install -g @forge/cli@latest on the command line to install the latest CLI version.

15 Sep 2020

added Manifest validation in Forge CLI version 0.21.0

The CLI will now attempt to validate the content of the manifest.yml file, which holds the configuration of your Forge app. This validation happens when you run the forge lint, forge deploy, and forge tunnel commands.

If you want to force a deployment without running the validation, use the --no-verify argument. For example, you can run forge deploy --no-verify instead.

Run npm install -g @forge/cli@latest on the command line to install the latest CLI version.

updated in Forge CLI version 0.21.0

When running the forge install command, you'll be presented with the scopes from your most recent deploy in that environment. You'll also be prompted to confirm the installation of your app with these scopes.

Also, app installation will now fail if you run forge install before running forge deploy in any environment.

Run npm install -g @forge/cli@latest on the command line to install the latest CLI version.

bug fixes in Forge CLI version 0.21.0

This release includes:

• Improvements on the logging of complex objects when running the forge logs command.
• Improvements on error messages when failing to fetch templates while running the forge create command.
• A fix to prepend the app name to module keys only when creating a new app.

Run npm install -g @forge/cli@latest on the command line to install the latest CLI version.

14 Sep 2020

added CustomFieldEdit component for Jira custom field module in Forge UI version 0.6.0

You can now use the CustomFieldEdit component with the Jira custom field module, to further customize the editing experience of a custom field.

The onSave prop lets you create complex logic before a custom field value is saved and checked against the validation expression.

The gif above shows an example app that renders an editable custom field in a Jira issue.

Run npm install @forge/ui@latest on the command line to install the latest version of @forge/ui.

added New useEffect hook in Forge UI version 0.6.0

You can now use the useEffect hook in Forge UI to execute a function when one of the variables you’ve defined in the dependency array changes its value.

See useEffect for more details.

Run npm install @forge/ui@latest on the command line to install the latest version of @forge/ui.

1 Sep 2020

removed Forge API

For versions of @forge/api at less than or equal to version 0.1.7, all api.store methods are no longer available. These versions had been deprecated in a previous release.

Run npm install @forge/api@latest in your app directory on the command line to update to the latest version.

bug fixes in Forge CLI version 0.20.0

This release includes:

• A fix that enables support for Typescript dependencies.

Run npm install -g @forge/cli@latest on the command line to install the latest CLI version.

27 Aug 2020

updated Group data types and collection types in Jira custom field module

The Jira custom field module now supports:

• New data type group, where values are stored as strings that represent Atlassian group names.
• Collection types, which lets Forge custom fields store collections of values.

21 Aug 2020

added Jira issue activity module in Forge UI version 0.5.1

Jira Cloud now supports the Issue activity module, which renders content in the activity panel of Jira issues. The rendered content can be a list of changes, updates, and other information related to the issues.

Check out an example of IssueActivity and see Jira issue activity for more details.

added New template in the Forge CLI

A new template jira-issue-activity is now available when running the forge create command in the CLI. Use this template when creating apps with the Issue activity module.

18 Aug 2020

bug fixes in Forge CLI version 0.19.0

This release includes:

• When running a deprecated version of Forge CLI, a message to update your version is now displayed.
• If you encounter an error with Docker daemon when running the forge tunnel command, more information about the error is now displayed.
• Improvements on the logging of error objects.

Run npm install -g @forge/cli@latest on the command line to install the latest CLI version.

6 Aug 2020

added MacroConfig component for new macro configuration in Forge UI version 0.5.0

Forge macros can now use the new macro configuration. The new macro configuration displays configuration fields on the right side of a Confluence page. Any changes made in configuration values are automatically saved, and the macro is updated in context as well.

See Add configuration to a macro for more details.

removed ConfigForm component for macro config

The MacroConfig component replaces the use of the ConfigForm component for macro configuration. As a result, we're removing the ConfigForm component. We're also removing the config and defaultConfig props on the Macro component.

notice - deprecation Previous macro configuration API

The previous macro configuration API will be deprecated by 7 September 2020. On this date, the previous method for defining macro configuration will no longer be supported.

See Switch to the new macro configuration to know how to switch an existing macro with configuration to use the new macro configuration.

5 Aug 2020

added Confluence homepage feed module in Forge UI version 0.4.4

Confluence Cloud now supports the Homepage feed module, which lets you render content in a section of the right panel of the Confluence Home page.

The gif above shows an example Forge app on the Confluence Home page.

Run npm install @forge/ui@latest on the command line to install the latest version of @forge/ui.

updated Markup components for text component in Forge UI version 0.4.4

We've added markup components, which you can use as an alternative to markdown syntax for formatting text. See Text UI component reference documentation for more details.

Run npm install @forge/ui@latest on the command line to install the latest version of @forge/ui.

4 Aug 2020

added Guide for scheduled triggers

The Forge documentation now has a guide for developing an app with scheduled triggers. This guide gives brief instructions on how to manually invoke your function during development using a web trigger module.

20 Jul 2020

notice - deprecation Store API renamed to Properties API

We've renamed the existing store API to a new properties API. You'll need to use import { properties } from '@forge/api'; as we're no longer exposing it as a global API. The existing exported store API is still available, but will now emit warnings when used and will be removed in a future release of @forge/api.

See the Properties API for details.

added App storage API

Forge apps can now use the app storage API to store data with your app, rather than as a content or entity property within the Atlassian products. The app storage API stores data partitioned by Atlassian product and site. For example, you can't share data between Confluence and Jira on the same Atlassian site.

Note, the app storage API has limits and quotas.

Bug fixes in Forge CLI version 0.18.0

This release includes:

• Preservation of comments in manifest.yml when running the forge lint --fix command.
• The forge uninstall command now uninstalls the first highlighted installation, without needing confirmation with the space bar.

Run npm install -g @forge/cli@latest on the command line to install the latest CLI version.

15 Jul 2020

added Confluence global settings module in Forge UI version 0.4.3

Confluence Cloud now supports the global settings module, which lets you render content in Confluence global settings.

See GlobalSettings UI component reference documentation for more details.

Run npm install @forge/ui@latest on the command line to install the latest version of @forge/ui.

14 Jul 2020

added Scheduled trigger module

Use the Scheduled trigger module to invoke your Forge functions periodically, based on the scheduled defined in your app’s manifest.

added New template in the Forge CLI

A new template scheduled-trigger is now available when running the forge create command in the CLI. Use this template when creating apps with the Scheduled trigger module.

7 Jul 2020

Bug fixes in Forge CLI version 0.17.1

This release includes:

• Apps with more than 20 installation records will no longer break both install commands and post-deployment checks.
• API linter no longer fails for edge-case scenarios.

Run npm install -g @forge/cli@latest on the command line to install the latest CLI version.

6 Jul 2020

removed Tunnel support in staging environments

The tunnel command is no longer supported in staging environments.

See the Environment restrictions section on the Environments page for details.

notice - deprecation Forge CLI prior to version 0.17.0

Forge CLI versions older than 0.17.0 are deprecated. These versions being deprecated as the older packages are not compatible with the permissions changes introduced in this release.

Run npm install -g @forge/cli@latest on the command line to install the latest CLI version.

added App permissions

Forge now has app permissions. App permissions restrict the access that apps have to remote resources.

App permissions are declared in the manifest file. This is mandatory for all apps. If you do not declare app permissions in the manifest, API requests to OAuth 2 authenticated operations return a 401 error.

To declare app permissions, provide a scopes list that declares the OAuth 2 scopes required by your app to use an authenticated Product Fetch API on behalf of your user with asUser(). Apps in the development environment automatically receive the full list of available scopes.

The install command now supports an --upgrade argument, which upgrades the permissions for your Forge app. See Add scopes to call an Atlassian product REST API for instructions on upgrading Forge apps.

Run npm install -g @forge/cli@latest on the command line to install the latest CLI version.

added App linter in Forge CLI version 0.17.0

The lint command makes it easier to check your apps for configuration issues such as missing scopes. Errors detected by lint are fatal, while warnings are optional guidance. The lint command supports an optional --fix argument which attempts to automatically resolve errors where found.

The deploy command automatically calls the lint command as a pre-deployment check, with any detected errors blocking an app's deployment. In the case of false-positive errors, use the --no-verify argument to skip errors and warnings.

The tunnel command also calls the lint command on code reload, however both errors and warnings aren't fatal, so that you can iterate quickly without needing to restart the tunnel.

Run npm install -g @forge/cli@latest on the command line to install the latest CLI version.

Note, the lint command only supports the latest Atlassian cloud REST API versions. Support for older operations is a known limitation.

Bug fixes in Forge CLI version 0.17.0

This release includes:

• Headers passed to the http library are now included in the request.
• Fixes for complex log types during snapshot time.

Run npm install -g @forge/cli@latest on the command line to install the latest CLI version.

1 Jul 2020

added Optional icon property for Jira issue panels in Forge UI version 0.4.2

You can now choose to define the new property icon for Jira issue panels. If defined, a button would appear, which you’d need to click to add a panel to a Jira issue.

The gif above shows an issue panel rendering when the defined icon is clicked. See Jira issue panel for more details.

notice - deprecation Jira issue panels without icon property

In the future, it will be mandatory to define the icon property to use Jira issue panels. This means the issue panel will only work if the icon property is defined. We will announce this in the changelog when this happens.

added Confluence content byline item module in Forge UI version 0.4.2

Confluence Cloud now supports the Content byline item module, which displays Forge apps in the content byline section (the area under the page title) of a Confluence page.

The gif above shows a simple app that displays the status for the page.

See ContentBylineItem UI component reference documentation for more details.

added Confluence space settings module in Forge UI version 0.4.2

Confluence Cloud now supports the space settings module, which lets you render content in a tab inside the integration settings of a Confluence space.

See SpaceSettings UI component reference documentation for more details.

added Forge UI adds Code, SectionMessage, Toggle, and Tooltip in version 0.4.2

Use Code to display code snippets, and SectionMessage to alert users that a section of the application requires attention.

Use Toggle in a Form to view or switch between enabled or disabled states.

Wrap another component with Tooltip to display a tooltip when hovering over it.

Run npm install @forge/ui@latest on the command line to install the latest version of @forge/ui.

22 Jun 2020

added Function snapshot

A snapshot of the Forge app is now taken when starting a tunnel or on deployment. This reduces the startup time which leads to faster Forge functions. Taking a snapshot is enabled by default, but you can opt to disable it:

1
2
3

app:
  runtime:
    snapshots: false

For documentation, see Runtime reference.

Run npm install @forge/cli@latest on the command line to install the latest version of @forge/cli.

added Command suggestions in Forge CLI version 0.16.0

Mistyped or partially complete commands will now show suggestions.

Run npm install @forge/cli@latest on the command line to install the latest version of @forge/cli.

updated Forge JavaScript API reference

The Runtime API documentation for Forge has been updated and moved to JavaScript API.

The JavaScript API examples have been updated and additional information about the Forge JavaScript environment has been added.

11 Jun 2020

added Jira custom field module in Forge UI version 0.4.1

Jira Cloud now supports the custom field module, which makes it easier for app developers to add information to issues, specific to their teams' needs.

Check out the example apps to see the module in action:

• Issue Progress Custom Field
• Attachment Count Custom Field

See the CustomField UI component reference documentation for more details.

Run npm install @forge/ui@latest on the command line to install the latest version of @forge/ui.

28 May 2020

added New useSpaceProperty hook for setting space entity properties in Forge UI Confluence version 0.2.5

Developers can now easily store data against a Confluence space using the useSpaceProperty() hook.

See useSpaceProperty for more details.

27 May 2020

added Jira issue action module in Forge UI version 0.4.0

Check out an example of IssueAction and see Jira issue action for more details.

updated Lozenge component renamed to StatusLozenge

We’ve renamed the Lozenge component to StatusLozenge, to make it distinct from the DateLozenge component.

Run npm install @forge/ui@latest on the command line to install the latest version of @forge/ui.

26 May 2020

notice - deprecation Forge API

All versions of @forge/api at less than or equal to version 0.1.7 are deprecated. Only versions greater than '0.1.7' are supported. If your package is not updated, all api.store methods will be unavailable in future deployments.

Run npm install @forge/api@latest in your app directory on the command line to update to the latest version.

bug fixes Forge CLI version 0.14.0

This release includes:

• A fix that enables api.fetch to follow HTTP 303 redirects.
• A fix that enables type validation for Typescript apps on bundle time.

Run npm install -g @forge/cli@latest on the command line to install the latest CLI version.

14 May 2020

added Confluence context menu and content action modules

Confluence Cloud now supports the following new modules:

• Context menu: Display an app in the context menu when a user highlights text. The gif above shows an example app that gives the definition of the selected word.
• Content action: Display an app in the more actions (…) menu. The gif above shows an example app that gives information about the page.

11 May 2020

updated Uninstall command in Forge CLI version 0.13.0

The uninstall command in the Forge CLI now makes it easier to select and uninstall your app from multiple locations. The command first displays a table of locations where the app is installed. Navigate the table with the arrow keys, then select one or more locations to uninstall the app from. Finally, the command reports the result of each uninstall.

Note, the command still supports specifying the location by installation ID for backwards compatibility.

Run npm install -g @forge/cli@latest on the command line to install the latest CLI version.

7 May 2020

added Forge code snippets in the REST API documentation

The REST API documentation for Jira Cloud and Confluence Cloud now contain Forge code snippets. You can copy these snippets directly into your Forge app to make a product API call.

Note that you must be enrolled in the Forge beta and be logged in to Atlassian Developer to see these changes.

28 Apr 2020

bug fixes Forge CLI version 0.12.0

This release includes:

• A fix for an error that occurs when tunnelling with a handler file inside a subdirectory.
• A fix that enables the tunnel command to log all variable types.

Run npm install -g @forge/cli@latest on the command line to install the latest CLI version.

7 Apr 2020

added New documentation for Forge security

The Forge documentation now has a Security page. This page describes how the architecture, features, and policies of the Forge platform help make it secure. Note that this page is a conceptual overview and does not provide instructions for implementing security for your app.

30 Mar 2020

added Getting started tutorial for Jira

The documentation now contains a getting started tutorial for Jira. The tutorial takes you through adding a panel to a Jira issue to display the number of comments on the issue. Note, we've kept the Confluence getting started tutorial as well.

See Build a Jira hello world app to work through the tutorial.

added Forge CLI support for a storage API in version 0.11.0

The api object now includes a store component that lets you persist data between invocations of your app. For example, in the app code, you can use:

1
2
3
4

import api from '@forge/api';

await api.store.onConfluencePage('id').set('my-key', 'my-value');
const value = await api.store.onConfluencePage('id').get('my-key');

See Store API for more information.

Note, you need to have the latest version of @forge/api to use the storage API. To update, run npm install @forge/api@latest on the command line.

added Forge CLI support for FS module in version 0.11.0

Forge now supports the fs module. For example, in the app code, you can use:

1
2
3
4

import * as fs from 'fs';

fs.writeFileSync('./file.txt', 'Hello World');
const content = fs.readFileSync('./file.txt', { encoding: 'utf8' }); // content is 'Hello World'

Note, filesystem read/writes are in-memory and do not persist between invocations of the app.

added Forge CLI support for HTTP module in version 0.11.0

Forge now supports the http module. This provides better support for SDKs that use axios or node-fetch.

bug fixes Forge CLI version 0.11.0

This release includes:

• Better support for error messages when using console.error.
• Improved messaging for errors in system credential managers.

Run npm install -g @forge/cli@latest on the command line to install the latest CLI version.

27 Mar 2020

added New templates in the CLI

There are new templates available when running the forge create command in the CLI. We've also updated the names of the existing templates to align with the corresponding modules. Use these to hit the ground running when creating a new app.

Template list:

• blank
• confluence-macro
• confluence-macro-typescript
• jira-issue-glance
• jira-issue-panel
• jira-workflow-validator
• webtrigger

26 Mar 2020

added Tutorial for Jira workflow validator

The Forge documentation now has a tutorial for building a Jira workflow validator. This tutorial gives step-by-step instructions for building a Forge app that validates whether an issue is assigned when it transitions.

18 Mar 2020

added Forge UI adds IssueGlance and IssuePanel for Jira extension points in version 0.3.0

New documentation and examples for extending Jira with IssueGlance and IssuePanel components. See IssueGlance and IssuePanel in the UI components reference documentation for further details.

added Forge UI introduces Lozenge and DateLozenge components in version 0.3.0

Lozenge and DateLozenge are the first inline components we're shipping. We have updated the Text component to accept strings and inline components as children.

1
2
3
4
5
6

const App = () => (
  <Text>
    From <DateLozenge value={Date.now()} /> you can put text, inline components or
    **supported markdown** in here! <Lozenge text="wow" appearance="success" />
  </Text>
);

added Forge UI adds Avatar, AvatarStack, and ModalDialog in version 0.3.0

Avatar and AvatarStack support the existing UserPicker component to make working with users easier.

Use the ModalDialog component to prompt users to perform short-term tasks in your app.

Run npm install @forge/ui@latest on the command line to install the latest version of @forge/ui.

16 Mar 2020

updated Improved tunnel performance in version 0.10.0

Your app code will now reload faster when using the forge tunnel command. We've also updated the messages to notify you when the code starts and finishes reloading.

updated Create app uses dynamic values in version 0.10.0

Some manifest fields are now based on your app's name rather than the static value in the template when creating an app. The supported fields are key and title for macros, and key for web triggers.

bug fixes Forge CLI version 0.10.0

This release includes:

• Further improvements to error messages in the CLI.
• Better formatting and error handling when using console.log with JSON in the app runtime.
• Reduced idle CPU usage.

Run npm install -g @forge/cli@latest on the command line to install the latest CLI version.

11 Mar 2020

added Jira workflow validator, issue panel, and issue glance modules

The first Jira modules are available to try in Jira Cloud.

• Workflow validators: Create validators that apply to workflow transitions.
• Issue glances: Show a Forge app in the sidebar of Jira issues in the new issue view.
• Issue panels: Show a Forge app above the activity panel of Jira issues in the new issue view.

6 Mar 2020

added App permissions

You can now declare app permissions in the manifest. Permissions control the access apps have to Atlassian product REST APIs through scopes.

You'll be required to declare the app permissions in the manifest after 1 May 2020. Until then, apps that do not declare permissions will continue to receive the full list of available permissions.

See Add scopes to call an Atlassian REST API for instructions on adding scopes to Forge apps.

3 Mar 2020

added Forge CLI uses Docker to reduce the prerequisites in version 0.9.0

The Forge CLI no longer requires special tooling for Windows, Python, or libsecret. The Node.js requirement has also loosened to version 10.0.0 or later. Most of these were required for the forge tunnel command. Instead, the CLI uses a Docker image to manage these dependencies. These changes also decrease the package size, improving the install time.

Note, you need Docker to run the forge tunnel command.

added Forge CLI supports ArrayBuffer responses in version 0.9.0

The Forge CLI now fetches ArrayBuffer responses. For example, in the app code you can use:

1
2

const response = await api.fetch('https://www.atlassian.com/');
const arrayBuffer = await response.arrayBuffer();

bug fixes Forge CLI version 0.9.0

This release includes:

• Forge API now exports methods according to the ES module standard. You can now import individual methods as well as the default api export.
• Users without keytar no longer need to use environment variables to log in.
• Improvements from UX feedback, including improved error messages.

Run npm install -g @forge/cli@latest on the command line to install the latest CLI version.

28 Feb 2020

added New documentation for Forge debugging

The Forge documentation now has a debugging page. This page lists common errors that you may see when developing a Forge app. It also describes the Forge tools that are available to diagnose errors during debugging, such as logging and tunneling.

24 Feb 2020

added New documentation for Forge UI

The Forge documentation now has a Forge UI page. This page describes the main Forge UI concepts: components, hooks, and event handlers. Note that the existing Forge UI hooks page has been removed in favor of this new page.

18 Feb 2020

added Forge UI supports macro configuration in version 0.2.0

Users can now configure each instance of a Forge macro. Use the new ConfigForm and Macro components along with the useConfig hook to add configuration to your macro.

See Add configuration to a macro for instructions on adding configuration to a macro.

added Forge UI adds UserPicker component in version 0.2.0

A form component that provides a dropdown control populated with users, enabling one to select a user on the site.

Run npm install @forge/ui@latest on the command line to install the latest version of @forge/ui.

3 Feb 2020

added Forge CLI supports custom filenames for function handlers in version 0.8.0

The Forge CLI now enables you to use custom filenames for the handlers in the manifest.yml file. For example, you can use:

1

handler: myFile.myFunction

See the manifest entry in the reference section for more details.

added Forge CLI create command installs dependencies in version 0.8.0

The Forge CLI now installs the required dependencies when you create an app. This means you no longer need to run npm install after running forge create.

bug fixes Forge CLI version 0.8.0

This release includes:

• A fix to stop the tunnel closing when running the forge tunnel command.

Run npm install -g @forge/cli@latest on the command line to install the latest CLI version.

20 Jan 2020

added Forge CLI update notifier in version 0.7.1

The Forge CLI update notifier checks whether the CLI is up to date with the most recently released version. If your CLI version is behind, the CLI prompts you to update. We recommend keeping the CLI up to date to have the latest features and bug fixes.

bug fixes Forge CLI version 0.7.1

This release includes:

• A fix for the compatibility issues with Node 13. We recommend you continue using Node 12 to develop on Forge because it is the long-term supported version of Node.
• Performance improvements.

Run npm install -g @forge/cli@latest on the command line to install the latest CLI version.

10 Jan 2020

notice - change Forge logs

On 13 January 2020, we'll deploy a new logging persistence layer to Forge. We are making this change to improve our ability to provide fast and reliable logging for larger numbers of apps. This is an internal infrastructure deployment that does not add, remove, or change any of the functionality available in Forge.

When we deploy this change, any messages logged before that point will no longer be visible when you run the forge logs command in the Forge CLI.

6 Jan 2020

bug fixes Forge CLI version 0.6.2

This release includes:

• Fix for installation issues on the Windows platform.

Run npm install -g @forge/cli@latest on the command line to install the latest CLI version.

2 Jan 2020

added Example apps

See example apps for a list of open-source Forge apps. Use the apps as examples of what you can build with Forge. Explore them by reading the code, cloning the repo, and deploying the apps yourself.

9 Dec 2019

added Changelog

This changelog is the source of truth for all changes to the Forge platform that affect people developing Forge apps.

The changelog includes:

• Notices of upcoming change or deprecation.
• Feature additions, removals, and updates.
• Bugfixes.