Costkeel documentation

Public knowledge base source (host at https://greatwork.company/apps/costkeel/docs).

Get started (5 minutes)

1. Settings (Jira settings > Apps > Costkeel, Jira admins): pick the currency, time zone and alert thresholds; add your finance groups (see rates, cost per person, create budgets) and viewer groups (see budget totals, burn and forecast). Set default cost and bill rates for time no rule covers.
2. Rates and roles (Apps > Costkeel budgets, finance): give people roles and price the roles (for example Developer costs 72 an hour). Add person rules for exceptions and a "from" date for raises.
3. New budget: name it, choose what it covers (projects, an epic, a version or JQL), budget in cost, billable value or hours, set the dates and the amount (or an amount per month), and pick an alert issue and recipients. Save, and Costkeel calculates it from Jira's worklogs.

What a budget counts

• Scope. Projects: every issue in them. Epic: the epic, its child issues and their sub-tasks. Version: issues with that fix version and their sub-tasks. JQL: exactly what the JQL returns. The optional extra JQL narrows any of these.
• Period. Worklogs dated from the start date to the end date (or today, if earlier) in the site time zone.
• Cost. Every hour, priced with the cost rate that matches the worklog.
• Billable value. Billable hours only, priced with the bill rate. Work is not billable when the issue has a non-billable label or issue type, or the worklog comment has the #nobill tag (all in Settings).
• Hours. Every hour.
• Margin. Billable value minus cost.

Rates

• Each rule has a kind (cost or bill), optional conditions (person, role, issue type, project, label), an optional from and to date, and an hourly rate.
• The most specific rule wins. A person counts a little more than a role, so a person rule beats a role rule with the same number of conditions. Ties go to the later from date.
• A budget can carry its own rules (for example a contract rate); any matching budget rule wins over the site rules.
• Roles: add a row per person and role. Add another row with a from date when someone changes role; earlier worklogs keep the old role.

Plan, forecast and status

• Planned to date: the budget spread evenly over its days, or the monthly amounts you entered, each spread over that month's days.
• Forecast at completion: used so far plus the larger of (a) the remaining estimates on open issues in scope, priced at today's rates for the assignee, and (b) the average burn of the last 28 days carried to the end date.
• Status: Over budget (used is above the budget), At risk (forecast above the budget, or used more than 10% ahead of plan), On track, Not started, Ended, No time logged.

Recalculation

Costkeel stores each budget's totals so pages load fast. A worklog change anywhere on the site marks budgets as "Needs refresh"; the hourly job recalculates them, and anyone with access can press Refresh now. Changes to the budget, the rates or the settings also mark budgets for recalculation. Each budget is recalculated at least daily so remaining estimates stay current.

Alerts

Each threshold (default 80% and 100%) sends one Jira notification on the budget's alert issue (epic budgets use the epic when none is set) to the chosen people and groups, or to the budget owner. If the forecast goes over the budget, one more alert is sent. A threshold re-arms when the budget grows past it. Without an alert issue, alerts are listed on the budget only.

Reports

• Export CSV on the budget list: every budget with used, planned, forecast and status.
• CSV on a budget: totals by month, person, role, epic and issue, plus remaining estimates.
• PDF report on a budget: key figures, burn chart, monthly table, top epics, issues and people. Built in your browser.

Dashboard widget

Add Budget status (Costkeel) to a dashboard, then pick a project (its budgets) or tick budgets. Over-budget budgets are listed first. Viewers and finance see the widget; others see a message. On the new Jira dashboards, changes apply when you save the dashboard.

Classic Jira dashboards and their gadgets stop working on 17 May 2027, when Atlassian retires them. Before then, add the widget to a new Jira dashboard and pick the same settings.

Using Costkeel with Hourmint

Both apps read Jira's own worklogs and use the same rate rule model. Keep budgets and margin in Costkeel; invoice clients in Hourmint. Rates are entered in each app.

Limits

500 budgets per site, one currency per site, sub-tasks counted for the first 500 issues of an epic or version, the 300 largest issues listed per budget (totals include every worklog), no purchase orders or non-labor expenses.