Questions
What to run after a change, what to do when something breaks, and every command and word the course uses, each in one place.
Find what you just changed. The commands are in the order to run them, from the app folder.
With forge tunnel running, save the file and reload the Jira page: the tunnel serves your laptop’s code. Without the tunnel, deploy:
forge deployThe site picks up the new version on its own. You do not need to install again.
Check it, then deploy:
forge lint
forge deployIf the change adds a scope or a supplier host, forge deploy stops and asks for approval. See Deploy stops after a permission change.
A permission change makes a new major version. Approve it, then move each installation onto it:
forge deploy --approve MAJOR_VERSION_RULE
forge install --upgradeIf the app is installed on Jira and Confluence, run the upgrade for each; it asks which installation.
Variables reach your functions with the next deploy:
forge variables list
forge deployVariables belong to one environment. Without -e, both commands use development.
The desk is built from static/desk/src into static/desk/build, which is what Forge serves. Build, then deploy:
npm run build:ui
forge deployInstall it so package.json lists it, then deploy. Forge bundles what package.json and your imports name:
npm install @forge/api
forge deployDeploy and upgrade as for any permission change, then install the app on Confluence on the same site, once:
forge deploy --approve MAJOR_VERSION_RULE
forge install --upgrade
forge installIn the last command, choose Confluence and the same developer site. After that, each major version needs forge install --upgrade for both installations.
Find the message or the symptom. Each answer says why it happens and how to get going again.
That is expected, not an error. A new scope or supplier host makes a new major version, which you approve. Then each installation has to accept it, like a landlord signing a new licence:
forge deploy --approve MAJOR_VERSION_RULE
forge install --upgradeThe command ran outside the app folder. Change into the folder that holds manifest.yml and run it again.
Update the CLI and check the version:
npm install -g @forge/cli@latest
forge --versionA VPN or company proxy is intercepting HTTPS, and Node does not trust its certificate. Disconnect the VPN and try again. If your company needs a proxy, set it for npm with the values from your IT team:
npm config set proxy http://proxy.example.com:8080
npm config set https-proxy http://proxy.example.com:8080Do not use sudo. Install Node with a version manager such as nvm (opens in a new tab), then install the CLI again as yourself.
Your shell sets NODE_ENV. Clear it and install again:
unset NODE_ENVIn PowerShell: Remove-Item Env:NODE_ENV.
Update the CLI first. If it still fails, create a developer site in your browser at go.atlassian.com/cloud-dev (opens in a new tab). Either way, never build on your company’s real site.
Check that the app is installed on the site you are looking at (forge install list). Then open a work item and look for the app’s button under the summary: issue panels are added from there, once per work item.
The variable is missing in this environment, or you have not deployed since setting it:
forge variables set --encrypt API_NINJAS_KEY
forge deployWith forge tunnel running, your laptop runs the code, so the key has to be in your shell as FORGE_USER_VAR_API_NINJAS_KEY. In bash or zsh, read -s FORGE_USER_VAR_API_NINJAS_KEY && export FORGE_USER_VAR_API_NINJAS_KEY asks for it without echoing it.
API Ninjas did not accept the key. Copy it again from your API Ninjas account, set it again with forge variables set --encrypt API_NINJAS_KEY, and deploy.
API Ninjas answered 429: too many requests for your plan in a short time. Wait a minute and reload the work item.
The card looks up whatever the summary says. Rename the work item to a dish, such as “Pad thai” or “Miso soup”, and reload.
The supplier is not on the approved list, or the installation is still on the old major version. Check permissions.external.fetch.backend in manifest.yml, then approve and upgrade.
Apps that call Jira or Confluence on your badge (asUser()) need your consent once per person. Select Allow access, accept, and reload.
Stop it with Ctrl+C first, then deploy or upgrade, then start it again. Changes to the manifest only reach the site through a deploy, never through the tunnel.
On your own developer site that is fine: answer yes. On a company site, stop and use a developer site instead.
The code imports a package that is not installed. Install the one named in the message, then deploy:
npm install @forge/api
forge deployForge serves static/desk/build, which only exists after a build. Run npm run build:ui, then forge deploy. If it is still blank, check that resources in the manifest points at static/desk/build.
Usually the issue type. The app creates a Task in the space set by KITCHEN_PROJECT_KEY. If your space has no Task type, set another one and deploy:
forge variables set KITCHEN_ISSUE_TYPE Story
forge deployThe queue has no consumer. Check that manifest.yml has a consumer whose queue matches the key in new Queue({ key: 'menu-jobs' }), then deploy.
The prep cook ran into a problem. Read its log, which names the step that failed:
forge logs --since 15mThe usual causes are a missing KITCHEN_PROJECT_KEY, a project you cannot create work items in, or Forge LLM not being available on the site yet.
The notes have to name dishes the kitchen agreed to make. Write them plainly (“We will serve pad thai and a miso soup”) and send the menu again. If the logs show a Forge LLM error instead, check that the llm module is in the manifest and that you approved and upgraded after adding it.
Set the space key and make sure the app is installed on Confluence:
forge variables set MENU_SPACE_KEY KITCHEN
forge deploy
forge install --product confluenceThe pass checks four things before it hands a dish on: the ticket is in your kitchen space, it has the assign-to-agent label, its status is exactly the one in HANDOFF_STATUS (by default “Approved for Agent”), and it was not handed on before. The log says which check stopped it.
Rovo has to be active on the site, and the installation has to be on the version that added the agent. Deploy, approve and upgrade, then open Rovo Chat and browse agents.
Every command the course uses. Run them from the app folder.
Once per laptop, app or site.
npm install -g @forge/cli@latestforge --versionforge loginforge whoamiforge site provisionforge createforge registernpm installforge installforge install --product confluenceforge variables set --encrypt API_NINJAS_KEYforge variables set KITCHEN_PROJECT_KEY KITforge webtrigger createWhen you edit code, the manifest or the menu desk.
npm run build:uiforge deployforge tunnelWhen the manifest asks for more: new scopes or supplier hosts.
forge deploy --approve MAJOR_VERSION_RULEforge install --upgradeBefore a deploy, or when something looks wrong.
forge install listforge variables listforge lintforge lint --fixforge logs --since 15mWhen you are finished.
forge uninstallEach word is explained properly once, where the course first uses it. Here is the one-line version, its kitchen name, and Atlassian’s own page.
When a work item labelled assign-to-agent reaches the “Approved for Agent” status, the app hands it on once.
Runs in the Atlassian cloud, Back of house.Where the course explains it
The JavaScript in your app folder: the frontend that draws the UI and the functions that run in the cloud.
Lives on your laptop, Home kitchen.Where the course explains it
Calls a product API as the app itself. Needed when no user is present, such as in a queue consumer or trigger.
Runs in the Atlassian cloud, Back of house.Where the course explains it · Atlassian: Product REST APIs (opens in a new tab)
Calls a product API as the person using the app, with exactly their permissions.
Runs in the Atlassian cloud, Back of house.Where the course explains it · Atlassian: Product REST APIs (opens in a new tab)
A token from your Atlassian account that forge login uses to act as you.
Lives on your laptop, Home kitchen.Where the course explains it
Progress saved in storage as the worker goes, so a retried event skips the work already done.
Runs in the Atlassian cloud, Back of house.Where the course explains it
The function a consumer module runs for each queue event, after the original request has already returned.
Runs in the Atlassian cloud, Back of house.Where the course explains it
Your own HTML, CSS and JavaScript, served from a resources folder and shown in a sandboxed frame.
Runs in the browser, Front of house.Where the course explains it · Atlassian: Custom UI (opens in a new tab)
forge deploy uploads your code and manifest to the Atlassian cloud as a new version. It changes nothing on a site by itself.
Lives on your laptop, Home kitchen.Where the course explains it · Atlassian: forge deploy (opens in a new tab)
A free site of your own for building and breaking apps. Never use your company’s Jira for this course.
Atlassian’s own products, House systems.Where the course explains it · Atlassian: Provision a development site (opens in a new tab)
Forge blocks calls to the outside unless the host is listed under permissions.external.fetch.backend.
Declared in manifest.yml, The licence.Where the course explains it · Atlassian: Runtime egress permissions (opens in a new tab)
Forge keeps separate copies of each app: development (the default), staging and production, each with its own variables.
Runs in the Atlassian cloud, Back of house.Where the course explains it · Atlassian: Environments and versions (opens in a new tab)
A named value stored with the app, read in code as process.env.NAME. --encrypt hides the value from forge variables list.
Runs in the Atlassian cloud, Back of house.Where the course explains it · Atlassian: forge variables (opens in a new tab)
A service outside Atlassian that your functions call over HTTPS. Here it is API Ninjas, which returns recipes.
Outside Atlassian, Suppliers.Where the course explains it
One input becomes many outputs: one menu meeting becomes one Jira work item per dish.
Runs in the Atlassian cloud, Back of house.Where the course explains it
Atlassian’s app platform: you write the code, Atlassian hosts it, runs it and keeps it next to the product’s data.
Runs in the Atlassian cloud, Back of house.Where the course explains it · Atlassian: Forge overview (opens in a new tab)
Your code plus its manifest. One app can add several things to Jira and Confluence at once.
Runs in the Atlassian cloud, Back of house.Where the course explains it
@forge/bridge connects your frontend to Forge: invoke(), view.getContext(), router and more.
Runs in the browser, Front of house.Where the course explains it · Atlassian: Bridge API (opens in a new tab)
The forge command on your laptop. It creates, deploys, installs and tunnels your app.
Lives on your laptop, Home kitchen.Where the course explains it · Atlassian: Forge CLI reference (opens in a new tab)
Moves an installation onto a new major version so the site grants the new permissions.
Lives on your laptop, Home kitchen.Where the course explains it · Atlassian: forge install (opens in a new tab)
Checks the manifest and code before a deploy. --fix adds missing scopes it can infer from your code.
Lives on your laptop, Home kitchen.Where the course explains it
Large language models hosted by Atlassian, called with chat() from @forge/llm after declaring an llm module.
Runs in the Atlassian cloud, Back of house.Where the course explains it
Shows what your functions printed with console.log and any errors, for a site and environment.
Lives on your laptop, Home kitchen.Where the course explains it · Atlassian: Forge CLI reference (opens in a new tab)
An MCP server from Atlassian that gives AI coding tools current Forge documentation and guides while you work.
Lives on your laptop, Home kitchen.Where the course explains it · Atlassian: Forge MCP (opens in a new tab)
A relational database per installation, for data you query with joins and filters. This course uses KVS instead.
Runs in the Atlassian cloud, Back of house.Where the course explains it · Atlassian: Storage reference (opens in a new tab)
Runs your functions on your laptop while the site keeps calling them, so changes show up on refresh without a deploy.
Lives on your laptop, Home kitchen.Where the course explains it · Atlassian: Tunneling (opens in a new tab)
A named entry point in your code (handler: file.export) that Forge runs in the cloud when something calls it.
Runs in the Atlassian cloud, Back of house.Where the course explains it · Atlassian: Function reference (opens in a new tab)
A full page of your own in Jira’s Apps menu. Here the head chef pastes the notes from a menu meeting.
Runs in the browser, Front of house.Where the course explains it
A trigger filter that skips events the app caused itself, so its own edits don’t re-run it.
Declared in manifest.yml, The licence.Where the course explains it
forge install puts a deployed app on one site and product. You do it once per site; later deploys reach it automatically.
Lives on your laptop, Home kitchen.Where the course explains it · Atlassian: forge install (opens in a new tab)
The frontend’s way to call a resolver function by name and wait for its answer.
Runs in the browser, Front of house.Where the course explains it · Atlassian: Bridge API (opens in a new tab)
A module that adds your UI to the work item view, below the description.
Runs in the browser, Front of house.Where the course explains it
A Jira issue. In this course each work item names one dish, such as “Pad thai”.
Atlassian’s own products, House systems.Where the course explains it
The id the resolver returns at once, here menuId, so the page can ask about progress later.
Runs in the Atlassian cloud, Back of house.Where the course explains it
Forge’s hosted storage of JSON values by key, from @forge/kvs. Each installation has its own.
Runs in the Atlassian cloud, Back of house.Where the course explains it · Atlassian: Storage reference (opens in a new tab)
A deploy that changes permissions creates a new major version. You approve it, then each site has to accept it.
Declared in manifest.yml, The licence.Where the course explains it · Atlassian: Environments and versions (opens in a new tab)
The app’s description of itself: what it adds (modules), which files it serves (resources) and what it may do (permissions).
Declared in manifest.yml, The licence.Where the course explains it · Atlassian: Manifest reference (opens in a new tab)
One thing your app adds to a product, such as jira:issuePanel or trigger. Each has a unique key.
Declared in manifest.yml, The licence.Where the course explains it · Atlassian: Modules (opens in a new tab)
Forge tells your functions where they were called from, for example context.extension.issue.id.
Runs in the Atlassian cloud, Back of house.Where the course explains it · Atlassian: App context security (opens in a new tab)
Jira and Confluence REST APIs, called from functions with requestJira and requestConfluence.
Atlassian’s own products, House systems.Where the course explains it · Atlassian: Product REST APIs (opens in a new tab)
A trigger module runs a function when a product event happens, such as avi:jira:created:issue.
Runs in the Atlassian cloud, Back of house.Where the course explains it · Atlassian: Product events (opens in a new tab)
Async events: push a small message now, and a consumer function handles it later, with its own longer time limit.
Runs in the Atlassian cloud, Back of house.Where the course explains it · Atlassian: Events (opens in a new tab)
The small body you push to a queue. Keep it to an id and keep the real data in storage.
Runs in the Atlassian cloud, Back of house.Where the course explains it
Backend functions, each with a name, that the frontend calls with invoke(). They run in the Atlassian cloud, not in the browser.
Runs in the Atlassian cloud, Back of house.Where the course explains it · Atlassian: Forge resolver (opens in a new tab)
An action module: a function with typed inputs that a Rovo agent may decide to call.
Runs in the Atlassian cloud, Back of house.Where the course explains it · Atlassian: Rovo action module (opens in a new tab)
An AI agent your app adds to Rovo, with a prompt and a list of actions it may call.
Atlassian’s own products, House systems.Where the course explains it · Atlassian: Rovo agent module (opens in a new tab)
Every function invocation has a time limit. Work that may take longer belongs in a queue consumer, which can be given more time.
Runs in the Atlassian cloud, Back of house.Where the course explains it · Atlassian: Quotas and limits (opens in a new tab)
A permission such as read:jira-work that the app must declare before it may call a product API.
Declared in manifest.yml, The licence.Where the course explains it · Atlassian: Permissions (opens in a new tab)
A web trigger URL is public, so the app checks a secret header against an encrypted variable before doing anything.
Runs in the Atlassian cloud, Back of house.Where the course explains it
One Atlassian cloud site, such as your-name.atlassian.net, with its own Jira, Confluence and users.
Atlassian’s own products, House systems.Where the course explains it
An agent built in Rovo Studio in the browser, with no code and no app of its own.
Atlassian’s own products, House systems.Where the course explains it
forge create registers a new app and copies a working starter for the module you pick.
Lives on your laptop, Home kitchen.Where the course explains it · Atlassian: forge create (opens in a new tab)
Atlassian’s React components for Forge (@forge/react). They render natively and look like the product.
Runs in the browser, Front of house.Where the course explains it · Atlassian: UI Kit overview (opens in a new tab)
A webtrigger module gives your app a URL that outside systems can call over HTTPS.
Runs in the Atlassian cloud, Back of house.Where the course explains it