Jira Cloud

This guide explains how to connect Jira Cloud to an Faheem Code Enterprise Replicated installation. The integration lets users start Faheem Code from Jira issues by commenting with @faheem-code or by adding the faheemcode label. Faheem Code replies on the issue with a link to the conversation and posts the result back when it finishes.

Jira Cloud users are linked to Faheem Code accounts by email match: no Atlassian OAuth app is required, and users need no per-user setup beyond making their email visible (see User requirements). Users are enrolled automatically the first time they trigger Faheem Code.

Prerequisites

• Jira Cloud site administrator access, to invite the service account and register a webhook.
• An Faheem Code Enterprise organization admin or owner account, to configure the integration inside Faheem Code.
• Network access from Jira Cloud to the Faheem Code app URL over HTTPS with a publicly trusted certificate (for webhook delivery), and from Faheem Code to api.atlassian.com (for Jira API calls).

Create a service account

Create a dedicated Atlassian account for Faheem Code, for example faheem-code-bot@company.com. Faheem Code uses this account to read issues and post comments, and its replies appear under this account's name.

1. Invite the account to your Jira site and grant it access to every project where Faheem Code should read and comment.
2. Log in as the service account and create an API token at id.atlassian.com → Security → API tokens. Save the token somewhere safe. You will need it for the next configuration step below.

Warning

Mentions and labels made by the service account itself are ignored to prevent the agent from triggering itself. Always test from a regular user account, not the service account.

Enable the integration in the Admin Console

1. In the Faheem Code Enterprise Admin Console, open Config and check Enable Jira Cloud Integration under Jira Cloud Integration.
2. Save and deploy the new version, and wait for the rollout to finish.

After the deploy, a Jira card appears under Settings → Integrations in the Faheem Code app.

Configure the workspace in Faheem Code

As an organization admin or owner, open Settings → Integrations → Jira in Faheem Code and select Configure:

• Workspace: the full site hostname, for example yourcompany.atlassian.net. Webhook events are matched against this hostname, so the bare site name is not sufficient.
• Service account email: the service account's email address.
• Service account API token: the token created above. The credentials are validated against Jira when you save, so a typo fails immediately.
• Webhook secret: choose a strong secret. You will paste the same secret into Jira in the next step.

Save, then copy the events URL shown below the webhook secret field. It has the form:

https://app.<example-user-domain>/integration/jira/events

Register the webhook in Jira

In Jira, open Settings (gear icon) → System → WebHooks and create a webhook:

• URL: the events URL copied above.
• Secret: the same webhook secret entered in Faheem Code. Jira uses it to sign deliveries, and Faheem Code rejects unsigned or mis-signed events.
• Events: check Issue → updated and Comment → created. These are the only two events Faheem Code processes.
• Optionally scope the webhook with a JQL filter (for example project = ENG).
• Leave the request body included (do not check "Exclude body").

User requirements

Each user who wants to trigger Faheem Code from Jira must satisfy two conditions:

1. Matching email: the user's Atlassian account email must exactly match their Faheem Code login email.
2. Visible email: in the user's Atlassian account settings (id.atlassian.com → Profile and visibility → Contact → Email address), visibility must be set to Anyone. Jira omits the email from webhook payloads otherwise, and Faheem Code cannot match the user without it.

Warning

Atlassian can take 15 minutes or more to propagate an email-visibility change into webhook payloads. If Faheem Code replies that it could not determine your email address right after you changed the setting, wait and try again before assuming the setting is wrong.

No further setup is needed: the first successful mention enrolls the user automatically.

Start Faheem Code from an issue

• Comment @faheem-code followed by instructions on any issue in a project the webhook covers, or add the faheemcode label to the issue. Both the typed literal text and the mention selected from Jira's autocomplete picker work.
• To have Faheem Code work in a repository, include the repository URL (for example https://gitlab.com/group/project or https://github.com/org/repo) in the issue description or the comment. The triggering user must have that Git provider connected in Faheem Code, and exactly one repository should be mentioned. Without a repository, Faheem Code still answers on the issue but works without a workspace.

Faheem Code reacts with a comment linking to the conversation, and the service account posts the result back to the issue when the run completes.

Troubleshooting

• Faheem Code replies "Could not determine your Jira email address": the email-visibility requirement above is not met, or the change has not propagated yet. Verify the exact setting and retry after 15 minutes.
• A mention does nothing, with no reply at all: check that the comment was not made by the service account (those are ignored), that the user's Atlassian email matches their Faheem Code email, and that the webhook covers the issue's project. Jira Cloud does not show a delivery log for system webhooks, so check the Faheem Code logs (the faheem-code-integrations workload) or collect a support bundle.
• Logs show 403 Unidentified workspace: the Workspace field in the Faheem Code configuration does not equal the site hostname in the webhook payload. Re-open the configuration and set it to yourcompany.atlassian.net.
• Faheem Code replies that multiple repositories were found: mention exactly one repository in the issue and comment text.