Forge Manifest Editor

The Forge Manifest Editor extension allows you to configure your Atlassian Forge manifest files in an easy-to-use editor, as opposed to editing raw YAML. Making use of the editor's form systems (e.g. dropdowns, typeaheads, and custom fields for complex property values) allows you to make fewer mistakes and saves you valuable time in configuring your manifest.

This extension is a "custom editor" in VS Code allowing you to seamlessly edit, save, and redo any changes you make within the editor and have it reflect on the "real" manifest file. As such, it may change the formatting of your YAML as it is parsed back and forth between the editor and file, but we try to keep this to a minimum. Due to the nature of the custom editor being a large "form" like structure, we try our best to limit any bloat of "empty" properties into your manifest file. If you notice changes you make in the editor aren't being reflected in your manifest file, this is mostly likely due to the changes not being "complete" (empty properties, objects, or lists).

The extension is currently in an "alpha" state because while the extension is feature-rich enough to use and gain value from, it is lacking in certain areas of functionality support.

Due to added safeguards in the extension, any "unsupported" functionality of a Forge manifest should be preserved in your file.

Being in this "alpha" state allows us to get quicker feedback from the community on where there is need for improvement. We hope to reach a stable version of the extension as soon as time and scope allows. Feel free to reference below where we outline what is supported in this extension and the road map of what we plan to support in the future.

Usage

Install the extension via the banner above or by visiting the Visual Studio Marketplace

Once installed, you can make use of the forge manifest editor in two different ways:

Open Forge Manifest Editor In New Tab

1. Make sure to have an Atlassian Forge manifest.yml file open and focused.
2. Open the "Command Palette" either by clicking on "View > Command Palette" or invoking the key combination (default Ctrl+Shift+P).
3. Run the command "Forge Manifest Editor: Open Current File".
4. The custom editor will open in a separate tab and allow you to configure your Forge manifest file.

Reopen File With Forge Manifest Editor Versus Default YAML Editor

1. Make sure to have an Atlassian Forge manifest.yml file open and focused.
2. Open the "Command Palette" either by clicking on "View > Command Palette" or invoking the key combination (default Ctrl+Shift+P).
3. Run the command "View: Reopen Editor With...".
4. Select the "Forge Manifest Editor" option.
5. The custom editor will replace the default YAML editor you had open and allow you to configure your Forge manifest file.

You can also change the default editor in the same command window so that the "Forge Manifest Editor" opens by default instead of the VS Code YAML editor.

Functionality Supported

In general, we try to support everything that is GA; we may or may not support systems in Preview (by request or awareness); and we do not support systems in EAP (due to flux of potential changes).

Editor / Form Systems

• Fixed option list typeahead selection (single and multiple) for properties like permissions, module keys, etc...
• Dynamic list creation for properties like variables, domain URLs, etc...
• Collapsible fieldsets to help organize and minimize what is on the screen at the same time, allowing you to focus on the fields that you are currently trying to configure. This also allows the editor to not immediately showing optional nested fields.
• Preservation of property order in YAML. While using the editor to change your manifest, any updates sent back to the YAML file will attempt to preserve the ordering of properties you did manually before using the editor. For example, if you have a manifest that was pre-filled out due to the Forge CLI app creation via a template.
• Preservation of unsupported properties / data. If you are opting into an EAP or Preview status functionality of the manifest, it may not be supported in the editor. You will have to do it manually in the YAML and the editor will not display anything about it. The editor will also make sure to not delete these unsupported properties, preserving them to be worked on manually.
• Empty values/fields in the editor will not be present in the raw manifest YAML file. This is to make sure any fields/properties you haven't supplied a value to are not accidentally bloating your YAML file; making it hard to change/read manually if needed.

Top Level Manifest Properties

• App
• Modules (see below for list of supported modules)
• Permissions
• Endpoint
• Providers
• Remotes
• Resources
• Environment

Known Unsupported Properties

• Some modules (currently jira:customField and jira:customFieldType) have a schema property. This property is not supported by the editor as it's a complex JSON schema system. Support for this may come at a later date.
• Some modules have an EAP for i18n strings/objects for various properties. This is not supported in the editor currently as it is in EAP status.
• There is a top level property translations that is currently unsupported in the editor. This is due to it being in EAP status.
• There is a top level property connectModules that is currently unsupported in the editor. This is due to lack of documentation around how this field works.

Manifest Module List

Common Modules

• consumer
• function
• scheduledTrigger
• trigger
• webtrigger

Bitbucket Modules

• bitbucket:mergeCheck
• bitbucket:dynamicPipelinesProvider
• bitbucket:repoCodeOverviewCard
• bitbucket:repoCodeOverviewAction
• bitbucket:repoPullRequestCard
• bitbucket:repoPullRequestAction
• bitbucket:repoMainMenuPage
• bitbucket:repoSettingsMenuPage
• bitbucket:workspaceSettingsMenuPage

Compass Modules

• compass:adminPage
• compass:componentPage
• compass:dataProvider
• compass:globalPage
• compass:teamPage

Confluence Modules

• confluence:contentAction
• confluence:contentBylineItem
• confluence:contextMenu
• confluence:customContent
• confluence:globalPage
• confluence:globalSetting
• confluence:homepageFeed
• confluence:spacePage
• confluence:spaceSettings
• macro

Jira Modules

• jira:adminPage
• jira:customField
• jira:customFieldType
• jira:dashboardBackgroundScript
• jira:dashboardGadget
• jira:entityProperty
• jira:globalPage
• jira:globalPermission
• jira:issueAction
• jira:issueActivity
• jira:issueGlance
• jira:issueContext
• jira:issuePanel
• jira:issueViewBackgroundScript
• jira:jqlFunction
• jira:projectPage
• jira:projectPermission
• jira:projectSettingsPage
• jira:uiModifications
• jira:workflowValidator
• jira:workflowCondition
• jira:workflowPostFunction

Jira Service Management Modules

• jiraServiceManagement:assetsImportType
• jiraServiceManagement:organizationPanel
• jiraServiceManagement:portalFooter
• jiraServiceManagement:portalHeader
• jiraServiceManagement:portalProfilePanel
• jiraServiceManagement:portalRequestCreatePropertyPanel
• jiraServiceManagement:portalRequestDetail
• jiraServiceManagement:portalRequestDetailPanel
• jiraServiceManagement:portalRequestViewAction
• jiraServiceManagement:portalSubheader
• jiraServiceManagement:portalUserMenuAction
• jiraServiceManagement:queuePage

Known Unsupported Modules

• The Rovo modules (rovo:agent and action) are currently unsupported. These two modules are in Preview status and are on the extension roadmap to be supported soon.

Functionality Roadmap

• Support for Rovo modules (rovo:agent and action).
• Support for validation of "required" versus "optional" at a basic level. Showing errors/warnings to the user as needed.
• Support for validation of "required" versus "optional" at a more complex level. Dealing with properties that are only required under certain conditions or values of other properties.
• Tooltips or help buttons to provide descriptions and/or documentation around properties and their values.

Issue Tracker / Bug Reporting

Please feel free to send an email here to submit a bug/issue: zacharykipping+eorx2ix3w87ywdabgfcm@boards.trello.com

The public Trello board can be found here.

Contact Us

If you would like to further contact us about the extension, please reach out to forge@valiantys.com.