GUIDESetupJira
Jira Integration
Connect rkito to Jira to import issues as Change Intentions and keep status in sync bidirectionally.
Before you start
- A Jira account with admin access (webhooks need Jira admin)
- Your API domain, reachable over public HTTPS
- Access to the Atlassian Developer Console
What rkito uses Jira for
| Feature | Mechanism |
|---|---|
| Import Jira issue as CHI | OAuth 2.0 (3LO) — reads issues from connected site |
| Bi-directional status sync | Posts status updates back to Jira via API |
| Webhook callbacks | Jira pushes issue events to rkito (inbound) |
Create the Atlassian app
- Go to the
Atlassian Developer Consoleatdeveloper.atlassian.com/console/myapps/ - Click
Create → OAuth 2.0 integration - Name it
rkito
Configure OAuth 2.0 (3LO)
- In your app, click
Authorizationin the sidebar - Under OAuth 2.0 (3LO), click
Add - Set the Callback URL:
Environment Callback URL Production https://api.yourdomain.com/api/v1/integrations/jiras/installations/callback
Configure API scopes
Click Permissions in the sidebar and add these Jira API scopes:
| Scope | Why |
|---|---|
| read:jira-user | Read user profile of the authenticated user |
| read:jira-work | Read issues, projects, boards |
| write:jira-work | Post comments, update issue status |
| offline_access | Issue a refresh token for long-lived access |
Set environment variables
api/.env
# api/.env
JIRA_CLIENT_ID=<Client ID from Atlassian console>
JIRA_CLIENT_SECRET=<Secret from Atlassian console>
JIRA_REDIRECT_URI=https://api.yourdomain.com/api/v1/integrations/jiras/installations/callback
# Where to redirect after successful OAuth
APP_URL=https://app.yourdomain.comSet up inbound webhooks (optional)
Enables automatic CHI status updates when Jira issues change state.
- In Jira, go to
Settings → System → WebHooks(requires Jira admin) - Click
Create a WebHook - Configure URL:
https://api.yourdomain.com/api/v1/integrations/jiras/webhook - Subscribe to events: Issue created, Issue updated, Issue deleted
- Add the webhook secret to
api/.envasJIRA_WEBHOOK_SECRET
Connect from rkito
- In rkito, navigate to your org →
Integrations → Jira - Click
+ Connect→Connect Jira - A new window opens to Atlassian — log in and authorise rkito
- You are redirected back to
/integrations/jiras— the new integration appears in the table
Troubleshooting
invalid_redirect_uri
The JIRA_REDIRECT_URI env var must be character-for-character identical to what is registered in the Atlassian Developer Console — no trailing slash, no http/https mismatch.
Callback URL rejected by Atlassian
Atlassian requires HTTPS and a publicly reachable host. localhost and http:// URLs are rejected.
User redirected to localhost after OAuth
APP_URL in api/.env is still pointing at localhost. Update it to your BUI domain and restart the API.
Was this guide helpful?