How it works
Three small pieces in your systems, one app in Jira. Data only flows out of your systems.
Alpha. Tested end to end on Argo CD 3 with a Jira Cloud development site. Details may change before 1.0.
Syncotta has three small pieces in your systems and one app in Jira. Your systems only send data out; nothing connects into your cluster, your Git provider or Argo CD.
| Piece | Runs in | Does |
|---|---|---|
| Syncotta app | Your Jira Cloud site (Atlassian Forge) | Receives events, writes deployments to Jira, answers the gate, creates gate work items |
Notifications config (syncotta Helm chart) |
Argo CD Notifications, in your cluster | Sends a short event to Syncotta when a sync starts, succeeds, fails or degrades |
PreSync gate (syncotta Helm chart, gate.enabled) |
A Job in each gated application | Asks Syncotta before the sync and waits for the answer |
| GitHub Action (optional) | Your CI | Tells Syncotta which work items a pushed image belongs to |
Deployments in Jira
- Argo CD syncs an Application that carries the label
syncotta.com/payload=default(or=single-source). - Argo CD Notifications posts the event to Syncotta’s events address, with the instance’s notifications token.
- Syncotta checks the token, then queues the event and answers at once; Argo CD never waits for Jira.
- The queue worker maps the Argo CD destination to a Jira environment (the admin page’s environment list, or the
syncotta.com/environment-*annotations) and finds the work item keys. - It sends the deployment to Jira. Jira shows it on those work items, under Development > Deployments, and in the space’s Releases view.
Where work item keys come from
- the commit message of the synced revision (single-source apps with the
single-sourcelabel), - the
syncotta.com/issuesannotation on the Application, - CI: the GitHub Action reports the keys of an image (from the pull request title, the branch name and the commit messages of the push); when Argo CD later deploys that image, the deployment gets those keys.
A deployment without any key is not sent to Jira.
What the events carry: application name, namespace and project; destination; revision; sync phase, health and
times; image references; the syncotta.com/* annotations; the Argo CD URL for links. With the single-source label
also the commit message, which is used only to find keys and is never stored or logged.
The change gate
- The application’s chart includes the PreSync gate. Argo CD runs it as a Job before each full sync.
- The Job sends the application, the revision and the destination to Syncotta’s gate address, signed with the instance’s HMAC key.
- Syncotta keeps one gate record per application, environment and revision. On the first call it creates a Jira work item in the space and work type set in the admin page, for example “Deploy payments 2.4.1 to eu-prod”.
- Every 15 to 30 seconds the Job asks again. Syncotta reads the work item’s status (at most every 12 seconds; a status change in Jira makes it read again at once) and answers:
| Answer | When | The Job |
|---|---|---|
200 allowed |
The work item has an allowing status (for example Done), or the gate is off | Ends, the sync continues |
202 awaiting |
Any other status | Waits and asks again |
409 prevented |
The work item has a rejecting status | Fails the sync |
422 invalid |
The settings do not work (unknown space, work type or status), or the licence is not active and the licence policy is block | Fails the sync |
503 retry |
A temporary error | Waits and asks again |
Once a revision is allowed, further syncs of the same revision pass at once without a new work item. A new revision gets a new work item. If no answer is final before the Job’s deadline (default 30 minutes), the sync fails.
Fail policy (per Argo CD instance, in the admin page): what happens when Syncotta cannot reach Jira, and when the Syncotta licence is not active. Both default to Block the sync. A rejecting status always stops the sync.
Security in short
- Every request is authenticated before anything else is read: the events route with a bearer token, the CI and gate routes with an HMAC-SHA256 signature over timestamp, nonce and body, with replay protection.
- Tokens and keys are generated in the admin page, shown once, and kept in Forge secret storage. They are never put in URLs or logs.
- Syncotta runs on Atlassian’s cloud (Forge) and calls no other host. It stores settings, short-lived correlation records and gate records in Forge storage; it does not store author names, e-mail addresses or commit messages.
Next: Getting started, then Change gating.