Deployment: local, Forge, and company rollout¶

This is the end-to-end guide for taking this repository from a fresh clone to a working installation on a company Jira Cloud site. Follow the sections in order: first prove the code locally, then test it on a disposable Forge/Jira site, then deploy it to your company.

What Atlassian Forge is¶

Atlassian Forge is Atlassian's hosted platform for building Jira Cloud apps. This repository is the app's source code; Forge is the service that packages that code, runs its backend functions, stores its app data and secrets, and places its UI inside Jira. You do not run a separate application server for this project.

In this integration, the pieces have distinct responsibilities:

The manifest.yml file is the contract between this code and Forge. It declares the Jira modules that Forge should install, the API permissions the app needs, and the Kimai hostname Forge may call. npx forge deploy uploads the manifest and code to a Forge environment; npx forge install then connects that deployed environment to a Jira site.

Forge creates separate development, staging, and production environments for an app. They use separate deployments and storage, which is why testing on a demo/development site cannot alter the company production installation. Forge is only for Atlassian Cloud: this app does not install on Jira Server or Data Center.

Choose the right environment¶

Keep the three stages separate. A Forge app has independent development, staging, and production environments. A development installation is labelled (DEVELOPMENT) in Jira; it is for testing and is not the company rollout.

flowchart LR
  code[Clone repository] --> local[Local checks]
  local --> dev[Forge development\nenvironment + demo Jira]
  dev --> staging[Optional staging\ncompany test site]
  staging --> prod[Forge production\nenvironment + company Jira]

Do not point a development installation at the production Kimai instance unless your company has explicitly approved that test. Prefer a separate Kimai test instance or test account and project.

Before you start¶

You need the following people or permissions. One person can hold more than one role.

You also need:

• Node.js 22 (node --version should report v22.x);
• npm (bundled with Node);
• an Atlassian developer account for the development test. It does not need access to the company Jira site;
• a self-hosted Kimai URL that Forge can reach over HTTPS. It must use a valid public TLS certificate and must not be reachable only on a private LAN/VPN.

For a company deployment, create or use a company-owned Forge developer account or developer space. Do not make a personal Forge app the long-term owner of a company integration: the owner controls deployments, environments, and access to app data.

1. Clone and verify the repository locally¶

git clone https://github.com/jacksonpradolima/kimai-jira.git
cd kimai-jira
npm ci
npm run lint
npm run typecheck
npm test

These commands run the static checks and unit tests only. They do not call Forge, Jira, or Kimai, and they do not require secrets.

If you also want the full repository check (including generated UI documentation), run:

npx playwright install chromium
npm run check

2. Create your own Forge app for testing¶

The checked-out manifest.yml intentionally contains a placeholder app ID. The first time you use this source code, register a new app under your own Forge account:

npx forge login
npx forge settings set usage-analytics false
npx forge register kimai-for-jira-dev

forge register writes a new app ID to manifest.yml. That app and its data belong to the account that ran the command; it does not affect this repository's maintainer or their Forge app.

Register once for an app. Running forge register again generates a different app ID and disconnects the local manifest from the previous app's environments, variables, and storage. Keep the resulting manifest.yml local to this development/company deployment clone; do not commit an app ID or a company hostname back to this public repository.

Allow Forge to call Kimai¶

Before deploying, replace the placeholder in manifest.yml with the hostname of the Kimai server for this environment:

permissions:
  external:
    fetch:
      backend:
        - address: https://kimai-test.example.com

Forge denies outbound network calls unless the host is listed there. Use only the scheme and hostname—never place an API token, password, or other credential in this file. A different Kimai hostname requires a manifest change followed by another deployment and, in production, may require a Jira administrator to approve the app upgrade.

3. Deploy and test on a Forge demo Jira site¶

Before using --demo-site, provision a disposable development site. This is a separate operation from deployment:

npx forge site provision

Wait for the CLI to report the site as ready, then deploy to the default development environment and install the app:

npx forge lint
npx forge deploy --environment development
npx forge install --environment development --demo-site

--demo-site resolves your active demo Jira site. It is safe for development and does not install anything in your company Jira. Use --upgrade only when this app has already been installed on that same site; it cannot create or locate a missing demo site. After installation:

1. Open the demo Jira site and create or open an issue.
2. Confirm that the Kimai (DEVELOPMENT) issue panel appears in the issue view.
3. Open Jira administration → Apps → Kimai Integration.
4. Enter the test Kimai base URL. Optionally set default Kimai project and activity IDs for Jira-to-Kimai worklog synchronization.
5. Return to an issue, select Manage Kimai connection, and enter a Kimai API token for a test user.
6. Start/stop a timer or create a manual entry. Confirm that the expected Kimai timesheet is created.

Redeploy an existing development installation¶

After changing the app, run the checks and deploy to the same Forge environment:

npm run check
npx forge deploy --environment development

For ordinary code and UI changes, Forge automatically updates installations on the same major version. Refresh the Jira issue after the deployment completes. If the change updates manifest.yml permissions or allowed Kimai egress hosts, Forge will request a major-version approval; upgrade the existing development installation:

npx forge install --environment development --demo-site --upgrade

For a non-demo development site, replace --demo-site with --site your-dev-site.atlassian.net --product jira. Never run forge register again when redeploying: it creates a different app and does not update the existing installation.

For iterative code changes, keep this command running in a separate terminal:

npx forge tunnel --environment development

With a tunnel running, invocations from the development installation use your local code. Deploy again before testing a change without the tunnel, before using staging, or before promoting the change to production. Forge tunnels are not available in staging or production.

Demo-site provisioning is unavailable¶

The demo-site pool is operated by Atlassian. An error such as Demo site provisioning is temporarily unavailable (including No demo site found from forge install --demo-site) is not a problem with this repository or the deployed app.

1. Run npx forge site provision again later. Provisioning can continue in the background; the same command reports an active site when it becomes ready.
2. If the service remains unavailable, create a traditional Atlassian Cloud development site at Atlassian Cloud developer sites using the same Atlassian account. Complete its setup and ensure you are a Jira administrator there.
3. Install the development deployment on that non-production site instead:

npx forge install --environment development --site your-dev-site.atlassian.net --product jira

Do not use a company production Jira site as an ad-hoc development substitute. If you must use a company-owned non-production site, obtain the Jira administrator's approval first. Keep the Forge environment as development and use test Kimai credentials/data.

Test Kimai → Jira synchronization¶

The Kimai-to-Jira direction needs an inbound webhook:

1. In Kimai Integration, select Generate webhook secret and copy it now; it is only displayed once.
2. Copy the Forge web-trigger URL displayed on the same admin page.
3. In the Kimai test instance, create a webhook for timesheet.created and timesheet.updated that sends requests to that URL using the generated secret.
4. Create or update a Kimai timesheet associated with a Jira issue and check that the matching Jira worklog is created or updated.

See Kimai Setup for the Kimai-side details and Synchronization Model for current synchronization behaviour.

4. Prepare the company rollout¶

Before touching the production site, agree on these decisions with the company Jira and Kimai administrators:

• App ownership: the Forge app is registered under a company-controlled account or developer space, with more than one trusted contributor where possible.
• Kimai endpoint: the exact production HTTPS hostname is reachable from Forge and is listed in manifest.yml.
• Test boundary: the development/staging app uses non-production Kimai credentials and data.
• Defaults: decide whether Jira-created worklogs should use default Kimai project and activity IDs. They can be left empty if the workflow does not need them.
• User onboarding: each user will create and enter their own Kimai API token; an administrator cannot enter or read users' tokens for them.
• Webhook owner: a Kimai administrator is available to configure and maintain the webhook secret and destination URL.

Run the local checks again from the exact commit you intend to release:

npm ci
npm run check
npx forge lint

5. Deploy and share the company production app¶

From the company-owned deployment clone, with the production Kimai hostname already in manifest.yml, run:

npx forge deploy --environment production

For a company rollout, do not leave the production app's distribution status as Not sharing: Forge limits such an app to its contributors, so ordinary Jira users will see an access-denied page. After deploying, the Forge app owner must:

1. Open the app in the Forge developer console and select Distribution.
2. Under Distribution controls, select Edit, choose Sharing, complete the app details, and save. Use the published Privacy Policy and Terms of Service URLs from this documentation site in the corresponding fields.
3. Under Installation link, select Jira, copy the generated link, and give it to a Jira site administrator.
4. Have that administrator open the link, choose your-company.atlassian.net, review the requested Forge scopes, and install the app.

The generated link is the installation path for non-contributor users. Keep it within the intended organization and regenerate it from the Distribution page if it is shared outside the intended audience. The production app is titled Kimai (without a development or staging suffix).

If Forge reports a major-version approval, read the listed change and explicitly approve it only if expected:

npx forge deploy --environment production --approve MAJOR_VERSION_RULE

Do not use --no-verify as a way to bypass that review.

6. Configure the installed company app¶

The Jira site administrator completes these steps after installation:

1. Open Jira administration → Apps → Kimai Integration.
2. Set the production Kimai URL. It must match the hostname declared in manifest.yml.
3. Set the optional default Kimai project/activity IDs if Jira worklogs should create Kimai timesheets with those defaults.
4. Select Generate webhook secret, store it in the company's approved secret manager, and copy the displayed Forge webhook URL.
5. Ask the Kimai administrator to configure the Kimai webhook with that URL and secret.
6. Test with a non-critical Jira issue and a pilot user before inviting all users.

Each user then performs their own setup:

1. Open any Jira issue and find the Kimai panel.
2. Select Manage Kimai connection.
3. Paste their personal Kimai API token and save.
4. Create a small manual time entry or start/stop a timer to confirm access.

Tokens and webhook secrets are stored in Forge Secret Store. They are not committed to Git, exposed on the admin page after creation, or visible to other users.

Updating an existing company installation¶

Use the same release order every time: local checks, development test, optional staging test, then production deployment. For a production app already installed on the company site:

npx forge deploy --environment production

Keep the production Kimai hostname and Forge app ID stable. Re-running forge register instead creates a different app and loses the connection to the existing app's data. For a major permission or egress change, the Jira administrator must approve the upgrade from Atlassian's installation or connected-app flow before users can use the new permission.

If something does not work¶

• No Kimai panel in Jira: confirm that deployment and installation target the same Forge environment and site, then refresh the issue view.
• Kimai calls fail: confirm the URL is public HTTPS and its hostname exactly matches permissions.external.fetch.backend in manifest.yml; deploy again after changing it.
• forge says you are not logged in: run npx forge login using the intended company/development account.
• Webhook returns 401: regenerate/check the shared secret and signature settings; see Troubleshooting.
• Need more detail: see Development, Installation, Configuration, and Kimai Setup.