Skip to content
FluxGate

Enterprise · Jira and Jev AI

Jira setup

One Jira Automation flow and three status rules in FluxGate let a Jira status change request, approve and deploy a release.

4:43 videoBuilds on:Approvals and policies

Before you start

  • A Jira Cloud sandbox with the project CHK, the ticket CHK-142, and the workflow To Do, In Review, Approved, Done. The status names in your workflow must match the status rules you create below. If your workflow has no Approved status, add one or type the name of the status you use.
  • A Jira API token for the Jira user that FluxGate comments as. This user needs the permissions Browse projects, Add comments and Link issues.
  • A public HTTPS address that Jira Cloud can reach for the backend port 8080. On a laptop, use a tunnel (see below).
  • The backend runs with FLUXGATE_ENCRYPTION_KEY set. FluxGate needs it to store the Jira token. See Install and first boot.
  • Sign in as admin System admin and select the team Checkout. Only a system admin or a Team Admin can open the Jira page. priya and sam see "Access Denied".

How the connection works

FluxGate does not poll Jira. Jira calls FluxGate when a ticket changes status, and FluxGate decides what that status means.

  1. A Jira Automation flow runs when a work item changes status. It sends a web request to the Events URL of your integration.
  2. FluxGate checks the secret in the Authorization header and reads the ticket key, the new status and the labels of the ticket.
  3. FluxGate runs its status rules from top to bottom. Each rule says: when a ticket reaches this status, do this action in these environments.
  4. Optionally, FluxGate writes the result back to the ticket as a comment and a link.

One integration covers one Jira project. Create one integration for each project.

Which environment does a ticket mean?

The Environment field tells FluxGate where to read the environment from. It is labels by default, so a label on the ticket names the environment. A label that equals the environment name (Production) works as it is. For any other word, add an alias. In this chapter the alias prod maps to Production. A ticket with no matching label does nothing, and the event log reads "No rule matched."

FluxGate acts only on features that are linked to the ticket. Jira end to end shows how to link one.

Status rules

A status rule has three parts: a Jira status, an action and an optional list of environments. The status matches without regard to case and spaces. The actions are:

ActionWhat FluxGate does
RequestAsks for a deployment through the normal path, so your approval policy creates a pending request. It works on a stage that is not deployed, rejected, or rolled back.
ApproveCloses the pending request as approved by Jira. It works only in an environment listed under Jira approves in.
DeployDeploys a stage that is already approved. On any other stage it refuses, writes the reason to the log, and changes nothing.
Roll backReverses a deployment.

This chapter uses three rules: In Review requests Production, Approved approves it, Done deploys it. Deploy never approves for you.

Trusted approvals

For the environments listed under Jira approves in, the Jira status you choose counts as the approval. No FluxGate approver votes. FluxGate does not map Jira users to FluxGate users. It records the ticket key, and the Jira user name when the event carries one.

The write-back token

Write-back lets FluxGate answer on the ticket. You give it the email of a Jira user and an API token. FluxGate encrypts the token with FLUXGATE_ENCRYPTION_KEY before it stores it, and it never shows the token again. If the key is missing, saving a token fails with encryption_key_missing. Changing the Jira base URL to another host later clears the token and turns write-back off.

The public Events URL and the tunnel

Jira Cloud calls the Events URL from the internet, so the URL needs a public https:// address. FluxGate shows the URL as your browser reaches the backend. On the demo stack that is http://localhost:8080/..., which Jira cannot reach. Run a tunnel to port 8080 and swap the host part of the URL for the tunnel address. Keep the path.

Start a tunnel to the backend
ngrok http --host-header=localhost 8080 --pooling-enabled

ngrok prints a forwarding address such as https://<name>.ngrok-free.dev. Only the path /api/v1/integrations/jira/<integration id>/events has to be reachable. Leave the tunnel running while you use the integration. Write-back goes the other way, from the backend to Jira over HTTPS, and needs no tunnel.

Create the integration

  1. Click Jira in the Settings group of the sidebar to open /settings/jira.
  2. Click New integration. The form New Jira integration opens.
  3. In Name, type Juniper Jira. In Jira base URL (optional), type your Jira site address, for example https://<your-site>.atlassian.net. Write-back needs this address later.
  4. Click Create integration. The toast "Jira integration created" appears.
  5. The Connection card shows the Events URL with Copy URL, the header Authorization: Bearer <secret>, and a one-time secret with Copy secret and I stored the secret. Click Copy URL and Copy secret.
  6. Paste the URL into a text editor. Replace http://localhost:8080 with the https:// address of your tunnel. Keep the path.

Create the Jira Automation flow

The names below are the ones Jira Cloud shows in a current site. An older site says project, rule and issue where a newer one says space, flow and work item.

  1. In Jira, open the settings of the CHK space and click Automation.
  2. Click Create flow, then Create from scratch.
  3. Pick the trigger Work item transitioned. Leave From status and To status empty, so every status change is sent. FluxGate's rules decide what each status means.
  4. Add the action Send web request.
  5. In Web request URL, paste the edited Events URL with the tunnel address.
  6. Set HTTP method to POST and Web request body to Issue data (Jira format).
  7. Tick the checkbox that delays later actions until the request has a response. A wrong secret then fails the run in the audit log of the flow.
  8. Under headers, add Authorization with the value Bearer <secret>. Tick Hidden, so Jira keeps the secret out of the rule.
  9. Name the flow FluxGate release and click Save and enable.

The web request

This is the finished request that the flow sends on every status change:

What the flow sends
POST https://<tunnel host>/api/v1/integrations/jira/<integration id>/events
Authorization: Bearer <integration secret>

<Issue data (Jira format) of the ticket>

FluxGate also accepts the header X-FluxGate-Jira-Secret: <integration secret> in place of Authorization. To check that the tunnel reaches the backend, send a request with no credentials:

Check the tunnel
curl -s -o /dev/null -w "%{http_code}\n" -X POST https://<tunnel host>/api/v1/integrations/jira/<integration id>/events
Expected output
401

The answer 401 proves the tunnel reaches FluxGate. It does not prove the integration id, because a wrong id answers 401 as well. The real proof is a test run: move a throwaway ticket, then look for Success in the flow's audit log and a new row in the Event log on the Jira page.

Set the environment mapping

  1. Scroll to the Settings card. Environment field already reads labels.
  2. Under Environment aliases, click Add alias. Type prod as the Jira value and pick Production as the environment.
  3. Under Jira approves in, pick Production. A warning appears: "In these environments a Jira status change approves without a FluxGate approver. Only add environments whose Jira workflow you trust to gate releases."
  4. Click Save settings. The toast "Jira integration saved" appears.

Save the settings before you add the approve rule. The rules editor reads the saved integration. If Production is not saved under Jira approves in, the approve rule row shows "No environment in this rule trusts Jira, so this rule will be refused."

Add the status rules

  1. Scroll down to the Status rules card, below Native webhook secret. Click Add rule three times.
  2. Row 1: set Jira status 1 to In Review, Action 1 to Request and Environments 1 to Production.
  3. Row 2: set Jira status 2 to Approved, Action 2 to Approve and Environments 2 to Production.
  4. Row 3: set Jira status 3 to Done, Action 3 to Deploy and Environments 3 to Production.
  5. Click Save rules. The message "Rules saved." appears.

Rules run from top to bottom. An empty environment list means every environment the ticket names. If there is no enabled approve rule, a deploy rule warns: "No enabled approve rule: deploy works only after a person approves the request in FluxGate."

Turn on write-back

  1. Scroll up to the Write-back card, above Native webhook secret. Switch on Enable write-back. Jira edition stays Jira Cloud.
  2. In Account email, type the address of the Jira user. In API token, paste the token.
  3. Switch on Post comments and Keep a FluxGate link on the issue.
  4. Click Save write-back, then Test connection. FluxGate reports success with a message such as connected as <display name>.

The exact text of the comments and the link that FluxGate posts, and how Jira Cloud shows them, is covered in Jira end to end. Click Save write-back before Test connection: the test uses the saved settings. If the integration has no Jira base URL, the page asks you to set it first. A failed test reads Jira returned 401 or could not reach Jira: ....

Examples

The finished integration

PartValue
NameJuniper Jira
Environment fieldlabels
Aliasprod maps to Production
Jira approves inProduction
Rule 1In Review, Request, Production
Rule 2Approved, Approve, Production
Rule 3Done, Deploy, Production
Write-backOn, with comments and a link

Good to know

  • The Native webhook secret card is the other route. Jira's built-in webhook can sign each request instead of sending the inbound secret. Click Generate, give the secret to the Secret field of a Jira Cloud webhook, and FluxGate checks the X-Hub-Signature header. A webhook without a secret is rejected. This chapter uses the Automation flow, so leave Generate alone.
  • Jira Automation can lag by several seconds. FluxGate processes an event while Jira waits for the web request.
  • The Jira flow audit log shows Success and Successfully published web request. It does not print the answer of FluxGate. A refused rule answers normally, so it shows only in the FluxGate Event log.
  • Only a system admin or a Team Admin can open /settings/jira.

Troubleshooting

Jira shows an HTML answer or the flow run fails

The free tier of ngrok can show a browser warning page. Add a second header to the web request: ngrok-skip-browser-warning with the value true.

The flow run fails with 401

The secret or the integration id in the URL is wrong. Check both. If you lost the secret, click Rotate secret on the Jira page and update the Authorization header in the flow.

The event log says "No rule matched."

The ticket has no label that names an environment, or the status has no rule. Add the label prod to the ticket and check the status names in the rules.

Saving the write-back token fails with encryption_key_missing

The backend runs without a valid FLUXGATE_ENCRYPTION_KEY. Set it as described in Install and first boot and recreate the backend.

Next

Link CHK-142 to express-checkout and drive a Production release from Jira in Jira end to end.