Integrations
Jira
On this page
What it does
- A Jira issue field on every change (a key such as
ABC-123), with a link to the issue, its summary and its status. - A comment on the issue when approval is requested, when the change is approved or rejected (with the reviewer's comment), and when it is published (revision, environment, flags). You choose which.
- Optionally a transition: for example In Review when approval is requested and Done when the change is published.
Connect Jira Cloud
- Pick the Atlassian account NanoFlags acts as. Comments appear under its name; a dedicated account (for example NanoFlags bot) keeps them recognizable. It needs Browse projects and Add comments on the projects you link, and Transition issues if you use transitions.
- Signed in as that account, create an API token at id.atlassian.com → Security → API tokens.
- In NanoFlags, open Settings → Integrations → Jira as an owner or admin and enter your site (
https://your-team.atlassian.net), the account's e-mail and the token. - NanoFlags checks the token (it reads the account's own profile) and shows the result. Test connection repeats the check.
Optionally limit links to some Jira projects (for example ABC, OPS): keys from other projects are refused. One Jira site per organization.
Link an issue to a change
Open the change, then Overview → Jira issue → Link issue, and type the key. Anyone who can create or edit changes in that environment can link, change or unlink the issue; each is recorded in the change's history.
Comments and transitions
| When | Comment | Transition (optional) |
|---|---|---|
| Approval is requested | Approval requested in NanoFlags for “New checkout” (Production, Shop) by Mona. | Transition when approval is requested |
| The change is approved or rejected | Omar approved “New checkout” in NanoFlags (Production, Shop). With the comment, if any. | — |
| The change is published | “New checkout” was published to Production as r42 (Shop) by Mona. With the flags. | Transition when published |
- Comments are written in your organization's language (English or Arabic) and link to the change in NanoFlags.
- A transition is found by its name or by the status it leads to. If the issue's workflow does not offer it from the current status (for example the issue is already done), it is skipped and noted in the delivery log.
- Failed deliveries are retried 5 times (after 1, 2, 4, 8 and 16 minutes) for rate limits, Jira server errors and timeouts. A retry first checks the issue for the earlier comment, so a comment is not posted twice. A refused token or an unknown issue is not retried.
Issue status on the change
The change page shows the issue's summary, status and status category (to do, in progress, done). NanoFlags reads them from Jira when the page is opened, at most once a minute per issue, and keeps them for 10 minutes. If Jira is slow or unreachable, the last known status is shown with its time.
Permissions and storage
- Only owners and admins connect, change or disconnect Jira. Credentials can only be entered from a signed-in dashboard session, not with a Management API token.
- The API token is encrypted (AES-256-GCM) by the NanoFlags notify service with a key the database does not hold. It is never shown again, returned by any API or sent to a browser.
- NanoFlags stores the issue key per change and, for display, the issue's summary, status and type. It reads nothing else from Jira.
- Disconnect deletes the token and the cached issue data. Issue keys on changes stay as plain references. Also revoke the token at id.atlassian.com.
Later: OAuth app
Phase 1 uses an API token of one Atlassian account, which needs no app installation. A later version will offer Connect with Atlassian through an OAuth 2.0 (3LO) app: an admin consents to scopes such as read:jira-work and write:jira-work, NanoFlags stores an encrypted refresh token instead of a personal API token, and calls go through api.atlassian.com/ex/jira/<cloud id>. Comments then show the app's identity. An Atlassian Marketplace app could add a NanoFlags panel inside Jira issues. Existing links and settings carry over.