Jaga integration

Jaga can serve as a project’s external task tracker. Deckhouse Code links task codes to Jaga, comments on referenced tasks, and can check commits and merge requests against those tasks.

Prerequisites

Ask an instance administrator to enable the fe_jaga_integration feature flag in the Rails console. The flag is disabled by default:

Feature.enable(:fe_jaga_integration)

To configure the integration for a project, you need the Maintainer or Owner role in that project. Group configuration requires the Owner role; instance configuration requires an administrator.

Use a Jaga account with access to the projects whose tasks the integration will process. Actions in Jaga use this account. The integration does not restrict task codes to particular Jaga projects, so grant the account access only to the projects whose tasks you intend to change.

A project can have only one active external task tracker: Deckhouse Code does not save Jaga in a project where another tracker is active. An active tracker inherited from a group or the instance blocks the save as well. Before you configure Jaga, open that tracker in the project, select “Use custom settings”, and deactivate it.

If Jaga is on a private network, ask an instance administrator to allow its host under “Admin” → “Settings” → “Network” → “Outbound requests”.

Configure the integration

1. Open the project and go to “Settings” → “Integrations” → “Jaga”.
2. Select “Active” under “Enable integration”.
3. Enter the base address of Jaga in “Web URL”, such as https://jaga.example.com. Enter the Jaga account credentials in “Email” and “Password”. Deckhouse Code uses <Web URL>/backend for API calls.
4. Under “Mentions”, select the sources that should create comments in Jaga: “Commits”, “Merge requests”, and “Issues”. Choose “Comment detail” to control whether the comment contains the title or full text.
5. Under “Jaga tasks”, set “Jaga task regex” or “Jaga task prefix” if task codes need a different pattern. By default, a task code is recognized when it starts with an uppercase Latin letter, followed by one or more uppercase Latin letters, digits, or underscores, then a hyphen and a number, for example JAGA-1.
6. Configure “Smart commits” and “Closing tasks” if commits should change tasks in Jaga.
7. Click “Save changes”. On a group or instance page, confirm with “Save” in the “Save settings?” dialog. On a project or group page, use “Test settings” to check the address and credentials.

The integration can also be configured for a group or the instance. Projects inherit those settings and can set their own. Changing “Web URL” clears the saved password; enter it again before saving. With http://, credentials and tokens travel without encryption.

By default, all three sources under “Mentions” are selected and “Comment detail” is set to “Title of the commit or merge request”. Smart commits and Jaga transitions are off. When you turn on smart commits, #comment and the status command are enabled, #time is disabled, and “Activity type” is develop.

Task links and mentions

A task code such as JAGA-1 in an issue, merge request, comment, or commit message becomes a link to <Web URL>/browse/JAGA-1. The project sidebar also has a “Jaga” link to the configured “Web URL”.

For the sources selected under “Mentions”, Deckhouse Code adds a comment to the Jaga task that links back to the object in Deckhouse Code. A missing task is skipped. A repeated mention of the same object does not add another comment. Comments use the Jaga account configured for the integration.

Mention comments, smart commits, and closing a task by a commit pushed to the default branch find a code only when the text contains a code shaped like JAGA-1 or another reference, such as #1 or a link. A code shaped like JAGA-1 is an uppercase Latin letter, optionally followed by uppercase Latin letters, digits, or underscores, then a hyphen and a number. A code of another shape, set with a custom regex, is silently ignored in a text without such a reference. Links rendered from task codes, push rules, the merge check, and closing through a merge request use the configured pattern directly.

Smart commits

Select “Run the commands of commits whose author has a Jaga account” under “Smart commits”, then enable the commands you need. The author email recorded in the commit must match a Jaga account. The configured integration account performs the actions in Jaga.

Put a task code and commands on the same line of a commit message:

JAGA-1 #comment Fixed the login form #in-review #time 1h 30m

• #comment adds the following text to the task comment.
• #in-review moves the task to an available status named “In review”. Replace it with a status name from your Jaga workflow, using hyphens for spaces; case is ignored. Only the first #word other than #comment and #time in a commit is treated as a status command; later ones are ignored.
• #time logs work time when the command and an “Activity type” are configured. The units are w, d, h, and m; one day is eight hours and one week is five days. An entry over 40 hours, such as 6d or 1w 1h, is ignored and nothing is logged for it. Jaga records the time under the integration account.

Commands run when the commit is pushed, including pushes to branches other than the default branch. Only the last 100 commits of a single push are processed; this also applies to mention comments and closing by commit. If the commit author has no Jaga account, the commands are skipped. When the commands complete, a comment is added even when “Commits” is cleared under “Mentions”.

The #time entries and the comment of a commit are skipped too when the task does not move to the named status: the task’s current status has no transition to it, Jaga refuses the change, or Jaga does not answer. They run the next time Deckhouse Code processes the commit, for example when the commit is pushed to a new branch or reaches the default branch. Pushing the same commit to the same branch again does not process it. If the status command names no status of the Jaga project, such as #wip, it stays plain text, and #comment and #time run.

Closing Jaga tasks

Under “Closing tasks”, select “Enable Jaga transitions” to move a task when a closing commit or merge request reaches the default branch. Write a closing reference such as Closes JAGA-1 or Fixes JAGA-1 in a commit message or, for a merge request, in its title, its description, or the messages of its commits. If a task prefix is configured, include it in the reference.

Choose “Move to done” for the first available status in the done category. Choose “Use target statuses” and enter workflow status names in order, separated by commas or semicolons (the hint under the field mentions only commas), to move through several available transitions. A transition that Jaga refuses leaves the task at its last reached status. When a task reaches the done category, Deckhouse Code adds a comment with a link to the closing commit.

Push rules

Configure Jaga checks under “Settings” → “Repository” → “Push rules” at the project, group, or instance level, as described in Push rules. The Jaga integration must be active at that level or inherited from above. The rules are off by default:

• “Reject commits naming a missing Jaga task” requires every new commit to name at least one existing task.
• “Reject commits whose author email is not a Jaga assignee of the task” requires every existing task named in a commit to be assigned to the commit author’s email, directly or through a Jaga group. The commit is rejected if a named task has no assignees or if no Jaga user has that email.
• “Jaga task statuses allowed for pushes” requires every existing task named in a commit to be in one of the listed statuses. The field accepts status names separated by commas or semicolons (the hint under the field mentions only commas); case is ignored. Like every push rule, it has a select with “Enabled” and “Disabled”. The rule applies only when “Enabled” is selected and the field lists at least one status; an empty field leaves it off.

With any Jaga push rule enabled, each new commit in pushed branches and tags must name at least one task that exists in Jaga. A code that Jaga has no task for does not reject the commit while the commit also names an existing task. Web editor commits and merge commits are checked as well. The first commit created through the web interface to populate an empty repository, such as an initial README, is exempt.

A push is also rejected when:

• it names more than 100 distinct task codes;
• Jaga cannot be reached or answers with an error, until Jaga answers without an error;
• Jaga rejects the integration credentials, until the credentials or the rules are changed;
• a rule inherited from a group or the instance remains enabled after the project deactivates Jaga.

The assignee check uses the author email stored in the commit. A person creating a commit can set that email; to identify who signed a commit, also enable the “Require GPG signature” push rule.

Push rules, including the Jaga ones, do not apply to a project that uses pull mirroring: neither mirror updates nor direct pushes to such a project are checked.

Merge check

In the project, open “Settings” → “Merge requests” → “Merge checks” and select “Title or description must name a Jaga task”. The integration must be active in the project or inherited. The check requires a matching task code in the merge request title or description; it does not query Jaga for that task.

The checkbox is unavailable until the Jaga integration is set up. If the integration is later deactivated, the check stays selected but no longer blocks merging.

If a Jaga push rule also requires a task code in every commit, put the code in the merge request title. The default merge commit message includes the title and is checked by the push rule. If the project has a merge commit message template, include %{title} in it, and keep the code when you edit the message before merging. With “Squash commits when merging”, the squash commit is checked too: its default message is the squash commit message template or, without a template, the merge request title. Include %{title} in that template as well.