Check new Jira change requests against your change policy
Build a Kovca workflow that starts when a Jira issue is created, checks the change request against a policy you write, comments with the result, and moves a compliant request to the next status.
Change requests (a production deploy, a config change, a firewall rule) get filed as Jira issues. Someone reads each one to see whether it follows the team's change policy: a rollback plan, a test note, a time window, and an approver when the change is risky. Incomplete ones bounce back and forth in comments. The ones that are fine wait in the same queue.
This guide builds a workflow that starts when an issue is created, checks the summary and description against sentences you write, comments with the result, and moves the issue only when the decision is compliant. You'll start from a template, test it, and activate it on the Jira account.
The template already uses the Jira Issue created trigger, Add comment, and Move issue. It does not store a Jira account. You choose the account when you activate. Until then the draft saves, and Studio tests simulate Add comment and Move issue.
Issue created does not have its own fields for a rollback plan, a test note, a time window, or an approver. The event fields are issue_id, issue_key, issue (the issue as JSON), and user (whoever produced the event, as JSON). The trigger's sample puts the summary at issue.fields.summary. This template also reads issue.fields.description. Rewrite the sentences for the words your team actually uses. The trigger's own sample is a password-reset issue, so don't run that sample against these sentences and expect a change review.
A fact on Policy Evaluation has to be text, a number, a boolean, or null. The description is not mapped as a fact, because Jira often stores it as a document rather than text. The text step includes it in the request. If that value is an object, the step inserts its JSON.
If someone already reads the queue, or the rollback plan and the time window already live in their own fields that a Jira transition can require, that is less machinery than this. The workflow is for the queue where those details sit in the description and the same comments get typed by hand.
What you'll build
The draft runs from Issue created through Policy Evaluation, then a switch into a passing comment and Move issue, or a gaps comment.
The ready branch does not post the gaps comment. The other branch does not move the issue.
Watch the test
Watch the Studio test (MP4). It is a screen recording of the production Studio, in light mode. The picture is labeled Studio test; Jira actions simulated. Idle time and the typing of the test input are cut, including a moment when the JSON was not yet valid. Nothing that remains is sped up. No Jira account is connected, and Send real requests stays off. Comment on the gaps returns its sample and is marked sample. That is not a skipped step, and it is not a comment posted in Jira. Move to ready is skipped on this input.
Studio test; Jira actions simulated. Decision is non_compliant. Comment on the gaps is marked sample. Move to ready is skipped. 5 credits used.
The recording follows these steps:
- Open Triggers. Jira is listed there, with 17 triggers, next to General.
- Open Jira under Action in an app. Add comment and Move issue are in that list, with the app's other actions.
- Select Issue created. No account is chosen. Project ID is 10000. Issue Type is Change.
- Open Activate. The checklist says up to 17 credits per event, and Connect Jira is still to do. The row is Publish and activate: run on every issue created. The button is not clicked.
- In Test, the input is the CHG-18 issue. Send real requests is off. Run. The decision is
non_compliantand the suggested action isreject, so the route isdefault. Comment on the gaps succeeded and is marked sample. Move to ready is skipped. The panel shows 5 credits used for that one Decision AI step. - A terminal then runs
/tmp/kovca test "Jira change review" --input /tmp/chg-18.json --json. That is the Kovca CLI'skovca testcommand, with no--live-actionsflag. It is the same kind of test: Policy Evaluation runs, and the Jira actions stay simulated. The printed decision isnon_compliant,movedis null,gap_comment_idis20931,gap_commentedis true, and the result says 5 credits.
The JSON later in this guide is the template test's gaps-branch result, where the policy step returns insufficient_information. It is not the decision on this recording. What Policy Evaluation returns depends on the sentences and the issue text.
Build it in the Studio
1Start from the template
Click Use this template above, or open Jira change review in Workflows.
The draft opens on the canvas. The components library is on the left. Triggers, AI, Action in an app, Data transformation, Flow, Core, and Human review are the groups. This workflow uses Jira, so Jira is under Triggers and under Action in an app. Apps you have not connected, and that this workflow does not use, stay behind Connect another app. The pictures below are the production Studio: that library, the Issue created settings, and a test of the CHG-18 issue. The template's step titles are the ones in the table above. The last card on the canvas is Result. That is the output step.
The library home. Jira is inside Triggers and Action in an app.
Issue created is one Jira trigger, in a list of issue, comment, sprint, and version triggers.
Add comment and Move issue are in the Jira action list, with the app's other actions.
The draft is not callable until you publish it. The Jira account is still to choose.
2The workflow starts when an issue is created
Select the input step. It is Jira: Issue created, not an API request. The account line asks you to connect Jira. Leave it empty while you test.
No Jira account is selected. Project ID and Issue Type are set.
Project ID is required. It is the project's numeric id, not the project key. The value above is a stand-in so the draft is valid before you connect. Replace it with your project before you activate. With an account connected, the field can list that account's projects. Issue Type is the type name. Change watches issues of that type, including a sub-task of that type. Clear it to watch every type in the project. Assignee, Reporter, and Status are optional filters, by Atlassian account id or by status name. The template leaves them unset.
The trigger description says it fires when an issue is created, including a sub-task.
Event fields later steps read:
issue and user are JSON. A path that is not there is left empty. The trigger sample's issue has fields.summary and fields.priority. It has no fields.description. Sample issue created in the Test tab is that sample: SUP-212, "Customer can't reset password". Those words are not a change request.
The same issue does not start two runs. Issue created names issue_id as the event id. A later delivery for that same issue id is not a new run. An edit to the issue does not start this trigger.
3Write the request the policy reads
Select Change request. It builds one line from the issue key, the summary, and the description. That line is Policy Evaluation's description. The issue key and the summary are also mapped as facts, so a sentence can name them as facts and not only inside the line.
For the CHG-18 example the line is:
CHG-18: Open the checkout firewall for the payments partner. Window: Tuesday 02:00-03:00 UTC. Test note: staging allowed the partner IP and blocked other IPs. No rollback plan. No approver.
A missing summary or description is an empty spot in that line. The fact summary is left off when issue.fields.summary is missing. It is not sent as an object. A summary that is not text, a number, a boolean, or null makes the policy step reject the input.
4Put your change policy in
Select Policy Evaluation. The description comes from Change request. issue_key and summary come from the event. The policy is a fixed value, so the rules live in the workflow. The inspector's request line says it is not set, because the request is filled by the fields under it (request.description, request.facts.issue_key, and request.facts.summary) rather than by one mapping of the whole request.
policy is a fixed value. request.description comes from Change request. issue_key and summary come from the event.
The node splits that text into rules on sentence boundaries. Each rule is one sentence. id and version are labels. They come back on the result when you set them. Rewrite the sentences in your own words. Keep each rule one sentence, and keep the policy to 40 sentences or fewer. The policy text can be at most 12000 characters.
The template's three sentences say:
- A change request may proceed when the description includes a rollback plan, a test note, and the time window, and, when the change touches production, customer data, a firewall rule, or configuration, a named approver.
- A change request that is missing a rollback plan, a test note, or the time window cannot proceed.
- A change that touches production, customer data, a firewall rule, or configuration and does not name an approver requires approval before it can proceed.
The node does not look up your Jira fields, your approver list, or your change calendar. If those words are not in the summary or the description, the sentences have nothing else to go on. A fact value can be at most 1000 characters, and there can be at most 50 facts.
decision is compliant, non_compliant, requires_review, or insufficient_information. suggested_action is proceed, reject, request_information, request_approval, or manual_review. requirements is a list of the rules that were judged, each with a status of satisfied, not_satisfied, requires_review, or insufficient_information. missing_information is the rules that were short of facts. What comes back depends on the sentences and the issue text. Run issues you have actually seen before you treat a route as settled.
5Move the issue only when the decision is compliant
Select Compliant?. The switch reads nodes.policy.output.decision and continues on the first matching case.
compliant goes to Passes comment. Every other decision goes to Gaps comment.
request_approval does not move the issue in this template. A risky change that still needs an approver stays on the gaps branch until you add a case for that suggested action. The template moves the issue only for compliant.
6Comment, and move the compliant ones
Passes comment, Comment that it passes, and Move to ready run only on ready.
Passes comment is this template:
Comment that it passes is Jira's Add comment action.
If it fails is Stop the run. The move does not run if this comment fails. Add comment is not idempotent: it is attempted once, and Kovca does not retry it. A second run with a new idempotency key can post another comment. Choose the Jira account on this step before you activate. Studio tests simulate it and do not post a comment. The simulated result is ok: true, id: "20931", and result: { "id": "20931" }. This template reads ok and id only.
Move to ready is Jira's Move issue action. It runs after the passing comment.
Issue (ID or key) is input.issue_key. Transition (ID or name) is Ready for approval. No Jira account is selected.
The optional comment on Move issue is unset, so the transition does not add a second comment. The transition value is a name or an id. Ready for approval is a stand-in. Replace it with a transition that exists on that project's workflow. The action does not list your transitions. If it fails is Stop the run. Move issue is not idempotent: it is attempted once. If the passing comment has already been posted and the move then fails, the comment is already on the issue. Studio tests simulate the move and do not change a status. The simulated result is ok: true and result: {}. This template reads ok only. It does not read inside result, because the catalog does not name those fields.
7Comment, and leave the others where they are
Gaps comment and Comment on the gaps run only on default.
Gaps comment is this template:
The requirements and the missing list are the node's own lists, inserted as JSON. An empty list shows up as []. The comment does not invent a missing rollback plan when the node did not report one.
Issue (ID or key) is input.issue_key. Comment comes from Gaps comment. If it fails, the run stops.
If it fails is Stop the run. The same rules as the other comment: attempted once, not retried, simulated in a Studio test unless Send real requests is on. The sample id is 20931 for this step too. That is the action's sample, not a second real comment.
8Test it
Open the Test tab. CHG-18 firewall and CHG-19 config are the template's examples. Sample issue created is the trigger's own sample, which is not this kind of change request. Leave Send real requests off. Add comment and Move issue then return their samples and are marked sample. Nothing is written to Jira. That sample is not what a published API call returns. The Test panel still charges Policy Evaluation when that step succeeds. It does not charge the run fee, and it does not charge a simulated Add comment or Move issue. See What it costs.
Studio test; Jira actions simulated. Decision is non_compliant. Comment on the gaps is marked sample. Move to ready is skipped. 5 credits used.
What Policy Evaluation returns depends on the sentences and the issue text. A compliant result takes Comment that it passes and Move to ready. Any other decision takes Comment on the gaps, and Move to ready is skipped. Steps that are not on the path are skipped. pass_comment, pass_comment_id, pass_commented, and moved come back null on the gaps branch. gap_comment and gap_commented come back null on the ready branch.
Before you activate, run issues you have actually seen, including ones that should move and ones that should not. When the routes look right, turn on Send real requests once, with the Jira account chosen, on an issue where an extra comment is harmless. Move issue will apply the transition for real on a compliant result.
Publish, call it, and activate it
The same workflow can be called over the API. The body uses the trigger's field names. Create an API key under API keys and keep it on your backend.
That curl calls a published workflow. The call runs Add comment for real, and Move issue as well when the decision is compliant. The steps need the Jira account you chose on them. If that account is missing, the action fails and, with If it fails set to stop, the run stops. A published call does not return the sample you see with Send real requests off.
The JSON below is the output this template's unit test expects for the CHG-18 input when Add comment is simulated and the policy step returns insufficient_information with suggested_action manual_review. That is one result the step can return. It is not a response from a published API call, and it is not necessarily the decision on the Studio recording. What the node returns for a given issue depends on the sentences and the issue text. In the example, gap_commented is true and gap_comment_id is 20931 because the simulated step's sample says so. That does not mean a comment was posted in Jira. Move issue did not run, so moved is null. The gaps comment is Gaps comment filled in from that result. CHG-19 is the other example. On a compliant result its moved comes from Move issue, and the gaps fields come back null.
Look up the run later. This returns status, timing, and steps. It does not return the output. Keep the execute response if you need the decision or the comment. Runs are kept for 30 days.
CHG-18 is a key you choose. Keys are kept for 24 hours. A retry with the same key and the same request returns the original run instead of posting another comment. A new key can comment again, and can move the issue again, because Add comment and Move issue are not idempotent. Kovca does not store the issue or the output.
To run it from Jira, open Activate. The checklist is what's left: connect Jira, and, once an account is connected, choose that account on the trigger, on both comment steps, and on Move to ready. It says up to 17 credits per event. The activate row is Publish and activate: run on every issue created. The button on that row says Publish & activate. That publishes the draft and starts it. A live automation runs that pinned version. Later edits don't reach it until you publish them to the automation.
Connect Jira is still to do. Up to 17 credits per event. Publish and activate runs on every issue created.
Connect Jira from the checklist, or from the trigger, when the routes in the Test tab look right. Until then, leave the account empty and keep Send real requests off.
A new issue starts a run when Jira sends the event. Follow runs on the Runs page (filter by the workflow). While an automation is paused, events that arrive are skipped. Kovca does not keep them to run later. A failed run is not retried on its own, because the comment or the move may already have happened.
If someone already reads the queue
You don't need this if a person can look at new change requests and the queue is small. Jira can require a field before a transition if that field exists on the issue, and a filter can collect the issues that are still in the first status. A field requirement does not read a paragraph, and it does not write the comment from a decision.
What the workflow adds is the same sentences on every new issue of the type you set, a comment that includes the decision, and a move only when that decision is compliant. You still choose the Jira account, set the project id and the transition name, and read a sample of results before you activate it.
Make it yours
- Rewrite the sentences. The three sentences are a fixed value on Policy Evaluation. Keep each rule one sentence. A path or a word the description does not contain is something the node cannot see.
- Point the transition at a real one.
Ready for approvalis a stand-in. Use the transition id or the transition name from the workflow on that project. - Set the type and the project you actually watch. Issue Type is
Change. Clear it, or type the type name your project uses. Replace Project ID10000with the numeric id. The project key is not this setting. - Leave non-compliant issues where they are. That is already what
defaultdoes. Add a case forrequires_reviewor forsuggested_actionrequest_approvalif those should move to a different status. That is a second Move issue step, with its own transition name. - Do not add Issue updated unless you mean every edit. Issue updated (
jira/issue_updated) fires when a field on an existing issue changes. It can fire very often. This template does not use it, so a comment you add does not start another run of this workflow. A new issue with a newissue_iddoes. - Keep the description short. The request the policy reads can be at most 2000 characters. A description stored as a large document can cross that and stop the run. Put the rollback plan, the test note, the time window, and the approver in the summary or in a short text description.
- Change it without surprising a live project. Edit the draft and publish the changes to the automation. The running version stays pinned until you do.
What it costs
Credits, and only for steps that succeed. Billing is the list.
A Studio test skips the run fee. It does not skip Policy Evaluation. That step is 5 credits when it succeeds, including a test with Send real requests off. A simulated action is not charged, and an action that fails is not charged. With Send real requests off, Add comment and Move issue are simulated, so they add nothing.
- A Jira event: 6 credits for the run.
- A published API call: 1 credit for the run.
- Policy Evaluation: 5 credits when it succeeds.
- Add comment: 2 credits when it runs for real and succeeds. Only the comment on the branch that runs is charged.
- Move issue: 2 credits when it runs for real and succeeds, and only on the ready branch.
The switch and the text steps use no credits. A branch that doesn't run isn't charged. The Activate panel adds every step together, including steps on branches that can't run in the same event, so its number is an upper bound for a live event. With this template that upper bound is 17 credits per event: the 6 credit event fee, Policy Evaluation, the passing comment, Move issue, and the gaps comment. A single event posts one comment, so a live event is 15 credits when the decision is compliant (the event fee, Policy Evaluation, the passing comment, and the move) and 13 credits otherwise (no move, and the other comment). The response's credits field is the run's total. See the workflows API, HTTP actions, and automations.