Jira integration for release readiness #682

gitstart-app · 2024-11-20T11:37:03Z

Implementation

We implemented a Jira API layer integrated with Atlassian’s OAuth2, allowing secure access to Jira data. Users can select their Jira organization during setup and configure multiple projects with custom “done” states and release filters (labels or fix versions).

The JiraIntegration model manages API calls for fetching projects, workflows, and tickets. We added “Project Management” as a new integration category in Tramline, with Jira as the first platform. The functionality, including OAuth flow, project setup, and ticket fetching, is thoroughly tested with fixtures and unit tests.

### Demo

https://www.loom.com/share/14b9a786dfa742d194f5f079d52b4766?sid=9554c7d6-414c-4f51-9caa-74004b473af1

gitstart-tramline · 2024-11-20T12:13:27Z

Hi @kitallis, PR is ready for review. Please review.

gitstart-tramline · 2024-11-25T09:24:18Z

Here are the steps to set up the Jira integration

To create an app for Jira integration and obtain the client_id and `client_secret, follow these steps:
Step 1: Create a Developer Account

Visit the Atlassian Developer Portal .
Sign in with your Atlassian account or create a new one.

Step 2: Create a New App

Navigate to the Developer Console.
Click on Create App and select the option for OAuth 2.0.
Provide the following details:
- App Name
- App Description
- API Permissions:
  - Required permissions: read:jira-work write:jira-work read:jira-user offline_access

Step 3: Set Redirect URLs

In the Authorization section, add the Callback URL: https://tramline.local.gd:3000/jira/callback

Locate the client_id and client_secret in Settings.

kitallis

I think functionally this works well. I will hack on the UI/UX bits myself in this PR to make it more consistent with Tramline, other than that, I've left various comments inline.

Thank you.

kitallis · 2024-12-03T07:45:50Z

app/controllers/integration_listeners/jira_controller.rb

+      else
+        @resources = @integration.providable.available_resources
+
+        if @resources.blank?
+          redirect_to app_integrations_path(state_app),
+            alert: t("integrations.project_management.jira.no_organization")
+          return
+        end
+
+        render "jira_integration/select_organization"
+      end


question: what scenario is this? afaik we select organization in the jira redirect itself, so why would we need to select again inside Tramline?

The Atlassian API endpoint https://api.atlassian.com/oauth/token/accessible-resources returns a list of all resources (organizations) the user has access to after authentication.
This is because:

Multiple Resources: The API does not automatically limit the response to the organization selected during the redirect. Instead, it provides all accessible organizations for the user.

User Selection in Tramline: To ensure the correct organization is used in Tramline, the app must present the user with the list of accessible organizations returned by the API. The user then selects the desired organization explicitly within the app.

kitallis · 2024-12-03T07:51:58Z

app/javascript/controllers/project_selector_controller.js

@@ -0,0 +1,37 @@
+import { Controller } from "@hotwired/stimulus"


suggestion: generally, we should try and create generic stimulus controllers as much as possible, because they are reusable.

even if that's not possible, we should avoid putting hyper-specific element names like jira_config inside the controller, because it not only makes it not reusable, but it also makes it non-reusable for non-jira project selections.

we made the controller generic and removed the specific names

kitallis · 2024-12-03T07:52:15Z

app/javascript/controllers/release_filters_controller.js

+import { Controller } from "@hotwired/stimulus"
+
+export default class extends Controller {
+  static targets = ["template", "container", "filter"]
+
+  add(event) {
+    event.preventDefault()
+    const content = this.templateTarget.innerHTML.replace(/__INDEX__/g, this.filterTargets.length)
+    this.containerTarget.insertAdjacentHTML("beforeend", content)
+  }
+
+  remove(event) {
+    event.preventDefault()
+    const filter = event.target.closest("[data-release-filters-target='filter']")
+    filter.remove()
+  }
+}


suggestion: I think this functionality is partly already covered in the nested_form_ext_controller.js – it supports generically creating list items and then also integrates positional dragging optionally.

see if we can reuse that controller here.

The logic differs between the two controllers. The super.add and super.remove methods in the NestedForm controller call the parent NestedForm class's add and remove methods, which handle the default behavior for adding and removing nested form elements. In contrast, the release_filters_controller.js manages basic DOM manipulations (inserting and removing content) without handling positional management or nested form logic. Therefore, reusing the NestedForm controller in this case may not be appropriate.

kitallis · 2024-12-03T07:53:46Z

app/javascript/controllers/project_states_controller.js

+import { Controller } from "@hotwired/stimulus"
+
+export default class extends Controller {
+  static targets = ["content"]
+
+  toggle(event) {
+    this.contentTarget.style.display = event.target.checked ? "block" : "none"
+  }
+}


suggestion: same as before, this is too trivial and general as an idea, we should make this functionality generic, additionally, we might have a controller that does something like this – just take a look at our current stimulus controllers.

kitallis · 2024-12-03T08:15:36Z

app/controllers/integration_listeners/jira_controller.rb

+    host = request.host_with_port
+    Rails.application.routes.url_helpers.jira_callback_url(
+      host: host,
+      protocol: request.protocol.gsub("://", "")


question: what is this gsub for?

the gsub is used to remove the //: always present on the protocol

kitallis · 2024-12-03T09:25:59Z

app/views/app_configs/project_management.html.erb

suggestion: we should avoid using jira-specific terminology in this view, we should fork off jira-specific code into its own partials (see other views/app_configs/* for reference)

kitallis · 2024-12-03T09:55:22Z

app/models/jira_integration.rb

+    with_api_retries do
+      response = api.search_tickets_by_filters(
+        project_key,
+        release_filters
+      )
+
+      return [] if response["issues"].blank?
+
+      Installations::Response::Keys.transform(response["issues"], TICKET_TRANSFORMATIONS)


thought: I think we should avoid using the transformations directly in the integration layer if possible. The general pattern that we use is to define the transformations in this layer and then pass them over to the api layer. This ensures that the output from the api layer is consistent across integrations

makes sense

kitallis · 2024-12-03T09:55:58Z

app/models/jira_integration.rb

+    with_api_retries do
+      response = api.projects
+      projects = Installations::Response::Keys.transform(response, PROJECT_TRANSFORMATIONS)
+      {projects: projects}


thought: see previous comment about transformations

kitallis · 2024-12-03T09:56:04Z

app/models/jira_integration.rb

+  def extract_unique_statuses(statuses)
+    statuses.flat_map { |issue_type| issue_type["statuses"] }
+      .uniq { |status| status["id"] }
+      .then { |statuses| Installations::Response::Keys.transform(statuses, STATUS_TRANSFORMATIONS) }


thought: see previous comment about transformations

kitallis · 2024-12-03T10:08:29Z

app/libs/installations/jira/api.rb

+    def build_jql_query(project_key, release_filters)
+      conditions = ["project = '#{sanitize_jql_value(project_key)}'"]
+
+      release_filters.each do |filter|
+        value = sanitize_jql_value(filter["value"])
+
+        case filter["type"]
+        when "label"
+          conditions << "labels = '#{value}'"
+        when "fix_version"
+          conditions << "fixVersion = '#{value}'"
+        else
+          Rails.logger.warn("Unsupported Jira filter type: #{filter["type"]}")
+        end
+      end
+
+      conditions.join(" AND ")
+    end


Suggested change

def build_jql_query(project_key, release_filters)

conditions = ["project = '#{sanitize_jql_value(project_key)}'"]

release_filters.each do |filter|

value = sanitize_jql_value(filter["value"])

case filter["type"]

when "label"

conditions << "labels = '#{value}'"

when "fix_version"

conditions << "fixVersion = '#{value}'"

else

Rails.logger.warn("Unsupported Jira filter type: #{filter["type"]}")

end

end

conditions.join(" AND ")

end

def build_jql_query(project_key, release_filters)

conditions = ["project = '#{sanitize_jql_value(project_key)}'"]

release_filters.each do |filter|

value = sanitize_jql_value(filter["value"])

filter_condition =

case filter["type"]

when "label" then "labels = '#{value}'"

when "fix_version" then "fixVersion = '#{value}'"

else Rails.logger.warn("Unsupported Jira filter type: #{filter["type"]}")

end

conditions << filter_condition if filter_condition

end

conditions.join(" AND ")

end

gitstart-tramline · 2024-12-06T09:02:15Z

Thank you for the review. We will work on the changes and get back to you.

gitstart-tramline · 2025-01-08T12:36:48Z

Hi @kitallis, PR is ready for review.

gitstart-app bot force-pushed the TRAB-646 branch from 1b4bc80 to b2f73a9 Compare November 21, 2024 12:48

kitallis requested changes Dec 3, 2024

View reviewed changes

gitstart-app bot marked this pull request as draft January 8, 2025 09:33

Jira integration for release readiness

7b12725

gitstart-app bot force-pushed the TRAB-646 branch from b2f73a9 to 7b12725 Compare January 8, 2025 12:13

gitstart-app bot marked this pull request as ready for review January 8, 2025 12:13

kitallis added 3 commits January 17, 2025 14:11

Merge branch 'main' into TRAB-646

306ee1d

Merge branch 'main' into TRAB-646

2ba7fbf

revive

4ecc7bd

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Jira integration for release readiness #682

Jira integration for release readiness #682

gitstart-app bot commented Nov 20, 2024 •

edited

Loading

gitstart-tramline commented Nov 20, 2024

gitstart-tramline commented Nov 25, 2024

kitallis left a comment

kitallis Dec 3, 2024

gitstart-tramline Jan 8, 2025

kitallis Dec 3, 2024

gitstart-tramline Jan 8, 2025

kitallis Dec 3, 2024

gitstart-tramline Jan 8, 2025

kitallis Dec 3, 2024

kitallis Dec 3, 2024

gitstart-tramline Dec 27, 2024

kitallis Dec 3, 2024

gitstart-tramline Dec 27, 2024

kitallis Dec 3, 2024

gitstart-tramline Dec 27, 2024

kitallis Dec 3, 2024

kitallis Dec 3, 2024

kitallis Dec 3, 2024

gitstart-tramline commented Dec 6, 2024

gitstart-tramline commented Jan 8, 2025

		@@ -0,0 +1,37 @@
		import { Controller } from "@hotwired/stimulus"

Jira integration for release readiness #682

Are you sure you want to change the base?

Jira integration for release readiness #682

Conversation

gitstart-app bot commented Nov 20, 2024 • edited Loading

Implementation

gitstart-tramline commented Nov 20, 2024

gitstart-tramline commented Nov 25, 2024

kitallis left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gitstart-tramline commented Dec 6, 2024

gitstart-tramline commented Jan 8, 2025

gitstart-app bot commented Nov 20, 2024 •

edited

Loading