gitlab-triage-linear-migrator 1.0.0.rc1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b631398c5c849d4879f5c4e299be58e02361a2a8fe73d3e145a66ffce0d4d58f
+  data.tar.gz: 1062431dbd7b9fcb994d94caa48002ecd616fe45b24f362cad9eba1c90496124
+SHA512:
+  metadata.gz: bfcf03533f44225e64e98c291a25102f8bba22d32906aed4440de705e9d321d745d458d24b0aac2b438c987d25428c7158af08e3ac67b7daa65bf86f9bb24359
+  data.tar.gz: 27607a1270f7500c1c70bcd73180e7f65da5a918b1a8b56ff81c4d230e9f8495d5daf86bd5fb0e55b2322581a2b7ecd9749d7d8811457c4d2b3c24cd8501ca8d

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,38 @@
+require: rubocop-rspec
+
+AllCops:
+  TargetRubyVersion: 3.1
+  NewCops: enable
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+RSpec/MultipleMemoizedHelpers:
+  Max: 10
+
+RSpec/NestedGroups:
+  Max: 6
+
+RSpec/ExampleLength:
+  Max: 10
+
+Metrics/MethodLength:
+  Max: 60
+
+Layout/LineLength:
+  Max: 200
+
+MultipleMemoizedHelpers:
+  Max: 20
+
+Metrics/ClassLength:
+  Max: 300
+
+# SubjectStub needed to be turned off because we have to stub `build_url` method to get the
+# API calls working. It is not a real concern here as we don't stub a method of the module
+# under test, but the method of the class we extend with the module.
+RSpec/SubjectStub:
+  Enabled: false

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Platform.sh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,158 @@
+<p style="text-align: center">
+<a href="https://www.upsun.com/">
+<img src="https://github.com/upsun/.github/blob/main/profile/logo.svg?raw=true" width="500px" alt="Upsun logo">
+</a>
+<br />
+<br />
+<a href="https://devcenter.upsun.com"><strong>Developer Center</strong></a>&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp
+<a href="https://upsun.com/"><strong>Website</strong></a>&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp
+<a href="https://docs.upsun.com"><strong>Documentation</strong></a>&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp
+<a href="https://upsun.com/blog/"><strong>Blog</strong></a>&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp
+<br /><br />
+</p>
+
+# Gitlab::Triage::Linear::Migrator
+
+Extends Gitlab Triage with an action that migrates issues and epics to Linear (https://linear.app).
+
+Initial version was developed by Platform.sh (https://platform.sh).
+
+## Installation
+
+TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after
+releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section
+with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+```
+
+## Usage
+
+### Preparation
+
+1. Create a policy file. You can use `support/triage_policies.example.yml` as a start/example. Read more about policy
+   files in the Triage Bot documentation: https://www.rubydoc.info/gems/gitlab-triage. This migrator provides an extra
+   `create_issue_in_linear()` action that can be used in a comment.
+2. Extend Triage Bot with the Linear Migrator
+    1. If you already have some extensions and using the --require option, simply add the below lines to the file
+    2. If not, create a new file e.g. `triage_plugins.rb` and paste the code below (you can also copy the file
+       `support/triage_plugins.example.rb`)
+3. Set the required environment variables. On top of the standard Triage Bot command line arguments, we need extra
+   options to
+   pass over to the Migrator. See the list below.
+
+#### Example policy
+
+```yml
+resource_rules:
+  issues:
+    rules:
+      - name: Create issue in Linear
+        limits:
+          most_recent: 500
+        conditions:
+          labels:
+            - "Linear::To Migrate"  # Remove this line if you want all issues to be migrated.
+          #state: opened # Remove this if you want closed issues to be migrated as well.
+          forbidden_labels:
+            - "Linear::Migrated"
+            - "Linear::Migration Failed"
+          ruby: "!labels.map(&:name).grep(/^Guild::.+$/).empty?" # Change this to match team_label_prefix parameter below!
+        actions:
+          comment: |
+            #{create_issue_in_linear(set_state: true, prepend_project_name: false, team_label_prefix: "Guild")}
+
+```
+
+Change the parameters as you wish:
+  - `set_state`: set to true if you want your imported issues reflect the current state (group label `S::` in GitLab).
+    Please note: issues in `S::Inbox` will be migrated to Triage if your team has Triage turned on in Linear.
+    If Triage is turned off, issues will have the default issue state, which is indicated (and can be set) on your
+    team's Workflow settings page in Linear.
+  - `prepend_project_name`: true means all imported issues will have their titles starting with the GitLab project name.
+    Set to false to simply copy the issue title as is.
+  - `team_label_prefix`: The migration requires a label in Gitlab that can be used to set the team name in Linear.
+    By default this label needs to be in this format `Team::Name of the team`. The team in Linear must be `Team: Name of the team`.
+    You can change the `Team:` prefix by setting this parameter to anything you want (e.g. Guild as in the example above).
+  
+This comment action will post a comment with a link to the new issue in Linear, add Linear::Migrated label and close the issue.
+  If the migration fails, it will add Linear::Migration Failed label and also some error debug information into the comment.
+
+#### Migrating epics
+
+If you want to migrate epics, you can add an Epics rule. Epics will be migrated as issues into Linear. Issues under epics
+will be migrated as sub-issues below the issue.
+
+```yml
+resource_rules:
+  epics:
+   rules:
+      - name: Create epic in Linear
+        # ...
+  issues:
+    rules:
+      - name: Create issue in Linear
+        # ...
+```
+
+Note that epics in Gitlab only exist in the group level, so `--source` should be `group` when running the Triage Bot.
+
+#### Extend the Triage Bot
+
+```ruby
+require "gitlab/triage/linear/migrator/issue_extension"
+Gitlab::Triage::Resource::Context.include Gitlab::Triage::Linear::Migrator::IssueExtension
+```
+
+#### Environment variables
+
+| Variable             | Description                                                                                                                                                                                          | Example                                   |
+|----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------|
+| LINEAR_API_TOKEN     | API token to access Linear. See https://developers.linear.app/docs/oauth/authentication                                                                                                              | `Bearer lin_oauth_ssdjw23242349020492342` |
+| IGNORE_LINEAR_DRYRUN | If this is set to anything, real Linear calls will be made when running Triage Bot with --dry-run. This is to test the migration on a test worspace without changing the opriginal issues in Gitlab. | `true`                                    |
+
+### Run from your local (testing)
+
+1. Simply run Triage Bot from the command line. 
+
+Migrate a group:
+` gitlab-triage --dry-run --token $GITLAB_API_TOKEN --source group --source-id gitlab-group --host-url https://your-gitlab-url.example.com --require ./triage-plugins.rb --policies-file 'triage-policies.yml'`
+
+Migrate a project:
+` gitlab-triage --dry-run --token $GITLAB_API_TOKEN --source project --source-id gitlab-group/project --host-url https://your-gitlab-url.example.com --require ./triage-plugins.rb --policies-file 'triage-policies.yml'`
+
+Migrate an entire instance:
+` gitlab-triage --dry-run --token $GITLAB_API_TOKEN --all --host-url https://your-gitlab-url.example.com --require ./triage-plugins.rb --policies-file 'triage-policies.yml'`
+
+
+See https://gitlab.com/gitlab-org/ruby/gems/gitlab-triage/#running-with-the-installed-gem for more.
+
+### Run from the CI (recommended)
+
+See https://gitlab.com/gitlab-org/ruby/gems/gitlab-triage/#running-on-gitlab-ci-pipeline.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can
+also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the
+version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version,
+push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/upsun/gitlab-triage-linear-migrator.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/gitlab/triage/linear/migrator/graphql_client.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+require_relative "query_logger"
+
+module Gitlab
+  module Triage
+    module Linear
+      module Migrator
+        # Client class for the GraphQL queries
+        class GraphqlClient
+          THROTTLE_RETRIES = 3
+
+          attr_reader :endpoint, :headers
+          attr_accessor :dry_run, :sleep_duration
+
+          include QueryLogger
+
+          def initialize(endpoint, headers = {}, dry_run: false)
+            @sleep_duration = 30
+            @endpoint = endpoint
+            @headers = headers
+            @dry_run = dry_run
+
+            @uri = URI.parse(@endpoint)
+            @http = Net::HTTP.new(@uri.host, @uri.port)
+            @http.use_ssl = @uri.scheme == "https"
+            @cache = {}
+          end
+
+          def query(query_string, variables = {})
+            log_query(query_string, variables)
+            cache_key = [query_string, variables].hash
+            return cached_result(cache_key) if cache_hit?(cache_key)
+
+            result = execute(query_string, variables)
+            cache_result(cache_key, result)
+            result
+          end
+
+          def mutation(mutation_string, variables = {})
+            if @dry_run
+              log_dry_run(mutation_string, variables)
+              return nil
+            end
+
+            log_query(mutation_string, variables)
+            execute(mutation_string, variables)
+          end
+
+          private
+
+          def cache_result(cache_key, result)
+            @cache[cache_key] = result
+          end
+
+          def cached_result(cache_key)
+            log_cache_hit(cache_key)
+            log_response(@cache[cache_key])
+            @cache[cache_key]
+          end
+
+          def cache_hit?(cache_key)
+            @cache.key?(cache_key)
+          end
+
+          def execute(graphql_string, variables)
+            retries = 0
+
+            while retries < THROTTLE_RETRIES
+              response = send_request(graphql_string, variables)
+              parsed_response = JSON.parse(response.body)
+
+              if should_retry?(response, parsed_response)
+                retries += 1
+                sleep(@sleep_duration)
+              elsif parsed_response["errors"]
+                errors_string = parsed_response["errors"].map { |error| error["message"] }.join(", ")
+                log_error(errors_string)
+                raise StandardError, "GraphQL Error: #{errors_string}"
+              else
+                return parsed_response
+              end
+            end
+
+            raise StandardError, "Rate limit reached after #{THROTTLE_RETRIES} retries"
+          end
+
+          def send_request(graphql_string, variables)
+            request = Net::HTTP::Post.new(@uri.request_uri, @headers)
+            request["Content-Type"] = "application/json"
+            request.body = { query: graphql_string, variables: }.to_json
+
+            response = @http.request(request)
+            log_response(response.body)
+            response
+          end
+
+          def should_retry?(response, parsed_response)
+            return false unless parsed_response.is_a?(Hash) && parsed_response["errors"].is_a?(Array)
+
+            response.code.to_i.between?(400, 499) &&
+              parsed_response["errors"].any? { |error| error.dig("extensions", "code") == "RATELIMITED" }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/gitlab/triage/linear/migrator/issue_extension.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require_relative "linear_connector"
+
+module Gitlab
+  module Triage
+    module Linear
+      module Migrator
+        # Extending Gitlab::Triage::Resource::Issue with functions required for Linear migration.
+        module IssueExtension
+          def discussions
+            # Epic discussions GET endpoint weirdly has id instead of iid as param.
+            url = if self.class.name.demodulize.underscore.pluralize == "epics"
+                    build_url(
+                      options: {
+                        params: { system: false },
+                        resource_id: resource["id"],
+                        sub_resource_type: "discussions"
+                      }
+                    )
+                  else
+                    resource_url(sub_resource_type: "discussions")
+                  end
+            network.query_api_cached(url)
+          end
+
+          def human_discussions
+            discussions.reject do |discussion_item|
+              discussion_item["individual_note"] == true && discussion_item["notes"].first["system"] == true
+            end
+          end
+
+          def extract_issue_id(text)
+            # Use a regular expression to match the issue ID pattern within the fixed text
+            issue_id_pattern = /Linear issue ID: ([a-f0-9-]{36})/
+
+            # Extract the issue ID using the pattern
+            match = text.match(issue_id_pattern)
+
+            # Return the issue ID if found, otherwise return nil
+            match ? match[1] : nil
+          end
+
+          def find_linear_id_in_gitlab
+            return if resource[:epic].empty?
+
+            url = build_url(params: {},
+                            options: { source: "groups", resource_type: "epics", resource_id: resource[:epic][:id],
+                                       source_id: resource[:epic][:group_id], sub_resource_type: "notes" })
+            comments = network.query_api_cached(url)
+            comments.each do |comment|
+              if (issue_id = process_comment(comment["body"]))
+                puts "Parent epic found: #{issue_id}"
+                return issue_id
+              end
+            end
+            nil
+          end
+
+          def process_comment(comment_body)
+            return unless comment_body.start_with?("Issue created in Linear:")
+
+            extract_issue_id(comment_body)
+          end
+
+          # @todo: make these configurable
+          LABEL_MIGRATION_FAILED = '/label ~"Linear::Migration Failed"\n/remove_label ~"Linear::To Migrate"'
+          LABEL_MIGRATED = '/label ~"Linear::Migrated"\n/remove_label ~"Linear::Migration Failed" ~"Linear::To Migrate"'
+          CLOSE_ACTON = "/close"
+
+          def create_issue_in_linear(set_state: false, prepend_project_name: false, team_label_prefix: "Team")
+            connector = setup_linear_connector
+            connector.team_label_prefix = team_label_prefix
+            project_name = if prepend_project_name
+                             fetch_project_name
+                           end.to_s
+
+            begin
+              log_processing_issue
+              issue = connector.import_issue(self, set_state:, project_name:)
+            rescue StandardError => e
+              handle_error(e.message, project_name)
+              return
+            end
+
+            return unless issue
+
+            construct_output(issue)
+          end
+
+          private
+
+          def log_processing_issue
+            puts Rainbow("Processing issue: #{resource["web_url"]}").yellow
+          end
+
+          def handle_error(message, project_name)
+            puts Rainbow(message).red
+            %(Issue migration failed for issue ##{resource["id"]} in project #{project_name} #{resource["web_url"]}
+Error:
+#{message[0..100]}
+#{LABEL_MIGRATION_FAILED})
+          end
+
+          def construct_output(issue)
+            %(Issue created in Linear: #{issue["url"]}
+Linear issue ID: #{issue["id"]}
+#{LABEL_MIGRATED}
+#{CLOSE_ACTON})
+          end
+
+          def setup_linear_connector
+            connector = LinearConnector.new
+            connector.gitlab_dry_run = network.options.dry_run
+            connector.linear_dry_run = ENV.fetch("IGNORE_LINEAR_DRYRUN", false) ? false : network.options.dry_run
+            connector
+          end
+
+          def fetch_project_name
+            network.query_api_cached(build_url(options: { resource_type: nil })).first["name"]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/gitlab/triage/linear/migrator/linear_connector.rb

@@ -0,0 +1,299 @@
+# frozen_string_literal: true
+
+require_relative "graphql_client"
+require_relative "linear_interface"
+
+module Gitlab
+  module Triage
+    module Linear
+      module Migrator
+        # Connects to Linear and creates stuff.
+        class LinearConnector
+          MIGRATION_LABEL_NAME = "Migrated from GitLab"
+          MIGRATION_IN_PROGRESS_LABEL_NAME = "Migrating from GitLab - in progress"
+          MIGRATION_LABEL_NAME_DRY_RUN = "Migrated from GitLab (DRY-RUN)"
+          MIGRATION_IN_PROGRESS_LABEL_NAME_DRY_RUN = "Migrating from GitLab - in progress (DRY-RUN)"
+
+          LINEAR_STATE_MAP =
+            {
+              "Inbox" => nil,
+              "InProgress" => "In Progress",
+              "OnHold" => "Blocked",
+              "PendingRelease" => "Pending Release",
+              "Planned" => "Planned",
+              "Review" => "In Review",
+              "Candidate" => "Candidate",
+              "Blocked" => "Blocked",
+              "Closed" => "Done",
+              "Testing" => "Testing",
+              "NeedsQA" => "Needs QA",
+              "DesignReview" => "Design Review",
+              "CodeReview" => "Code Review",
+              "ReadyForDev" => "Planned"
+            }.freeze
+
+          def initialize(gitlab_dry_run: false, linear_dry_run: false, client: nil, interface: nil, team_label_prefix: "Team")
+            @gitlab_dry_run = gitlab_dry_run
+            @linear_dry_run = linear_dry_run
+            @team_label_prefix = team_label_prefix
+
+            # @todo: Find a better solution to set the Linear API token.
+            @graphql_client = client || GraphqlClient.new("https://api.linear.app/graphql", {
+                                                            "Authorization" => ENV.fetch("LINEAR_API_TOKEN", nil)
+                                                          }, dry_run: @linear_dry_run)
+            @id_map = []
+
+            @query_count = 0
+            @mutation_count = 0
+            @query_count_by_function = []
+
+            @linear_interface = interface || LinearInterface.new(graphql_client: @graphql_client)
+          end
+
+          attr_accessor :gitlab_dry_run, :team_label_prefix
+          attr_reader :linear_dry_run
+
+          def linear_dry_run=(dry_run)
+            @linear_dry_run = dry_run
+            @graphql_client.dry_run = @linear_dry_run
+          end
+
+          def import_issue(gitlab_issue, set_state: false, project_name: nil)
+            linear_team_data = fetch_linear_team_data(gitlab_issue)
+            linear_label_ids = get_linear_label_ids(gitlab_issue.labels, linear_team_data["id"])
+
+            issue_data = prepare_issue_data(gitlab_issue, linear_label_ids, linear_team_data, project_name, set_state)
+            issue_created = @linear_interface.create_issue(issue_data)
+
+            return unless issue_created
+
+            if gitlab_issue.instance_of?(Gitlab::Triage::Resource::Issue)
+              import_mr_links(gitlab_issue,
+                              issue_created["id"])
+            end
+
+            import_comments(gitlab_issue, gitlab_issue.discussions, issue_created["id"])
+
+            if issue_created
+              handle_post_creation_tasks(gitlab_issue, issue_created["id"], issue_data["parent_id"], linear_label_ids,
+                                         issue_created["url"])
+            end
+
+            issue_created
+          end
+
+          def import_comments(_gitlab_issue, discussions, linear_id)
+            discussions.each do |discussion|
+              process_discussion(discussion["notes"], linear_id) if valid_discussion?(discussion["notes"])
+            end
+          end
+
+          private
+
+          def valid_discussion?(notes)
+            notes && !notes.empty? && notes.none? { |note| note["system"] }
+          end
+
+          def process_discussion(notes, linear_id)
+            return if notes.empty?
+
+            if notes.size > 1
+              process_threaded_comments(notes, linear_id)
+            else
+              create_comment_from_note(notes.first, linear_id)
+            end
+          end
+
+          def process_threaded_comments(notes, linear_id)
+            parent_note = notes.first
+            parent_comment = create_comment_from_note(parent_note, linear_id)
+            parent_external_id = parent_comment["id"]
+
+            notes[1..].each do |child_note|
+              create_comment_from_note(child_note, linear_id, parent_external_id)
+            end
+          end
+
+          def create_comment_from_note(note, linear_id, parent_id = nil)
+            @linear_interface.create_comment(
+              body: note["body"],
+              linear_issue_id: linear_id,
+              author_name: note["author"]["name"],
+              parent_id:,
+              created_at: note["created_at"]
+            )
+          end
+
+          def prepare_issue_data(gitlab_issue, linear_label_ids, linear_team_data, project_name, set_state)
+            {
+              title: format_issue_title(gitlab_issue, project_name),
+              description: sanitize_description(gitlab_issue.resource[:description]),
+              team_id: linear_team_data["id"],
+              create_as_user: gitlab_issue.resource[:author][:name],
+              assignee_id: determine_assignee_id(gitlab_issue),
+              state_id: determine_state_id(gitlab_issue, linear_team_data, set_state),
+              parent_id: determine_epic_id(gitlab_issue),
+              created_at: gitlab_issue.resource["created_at"],
+              label_ids: linear_label_ids,
+              due_date: gitlab_issue.resource["due_date"],
+              sort_order: gitlab_issue.resource["weight"]
+            }
+          end
+
+          def fetch_linear_team_data(gitlab_issue)
+            team_name = "#{@team_label_prefix}: #{get_team_label(gitlab_issue.labels)}"
+            linear_team_data = @linear_interface.get_team_by_name(team_name)
+            unless linear_team_data
+              raise StandardError,
+                    "Couldn't create issue in Linear, because the team #{linear_team_data["name"]} doesn't exists in Linear."
+            end
+
+            linear_team_data
+          end
+
+          def format_issue_title(gitlab_issue, project_name)
+            project_name.to_s.empty? ? gitlab_issue.resource[:title].to_s : "#{project_name}: #{gitlab_issue.resource[:title]}"
+          end
+
+          def sanitize_description(description)
+            return nil if description.nil?
+
+            description.gsub(/<!--(.*?)-->/m, "").gsub("...", ". . . ")
+          end
+
+          def handle_post_creation_tasks(gitlab_issue, issue_id, parent_id, linear_label_ids, issue_url)
+            handle_missing_parent_issue(gitlab_issue, issue_id, parent_id)
+            @linear_interface.create_comment(
+              body: compile_migration_notes(gitlab_issue.resource["web_url"],
+                                            gitlab_issue.labels), linear_issue_id: issue_id, author_name: "Migration"
+            )
+            @linear_interface.create_url_link(issue_id, gitlab_issue.resource["web_url"],
+                                              "Original issue in GitLab: #{gitlab_issue.resource["title"]}")
+            write_to_migration_map(gitlab_issue, linear_id: issue_id, linear_url: issue_url)
+            update_linear_labels(issue_id, linear_label_ids)
+          end
+
+          def handle_missing_parent_issue(gitlab_issue, issue_id, parent_id)
+            return unless gitlab_issue.resource["epic"] && parent_id.nil?
+
+            epic_url = gitlab_issue.host_url + gitlab_issue.resource["epic"]["url"]
+            @linear_interface.create_comment(body: "The original issue in GitLab has an epic that was not migrated to Linear. Epic in GitLab: #{epic_url}",
+                                             linear_issue_id: issue_id, author_name: "Migration")
+            @linear_interface.create_url_link(issue_id, epic_url,
+                                              "Epic in GitLab: #{gitlab_issue.resource["epic"]["title"]}")
+          end
+
+          def update_linear_labels(issue_id, linear_label_ids)
+            if @gitlab_dry_run && !@linear_dry_run
+              linear_label_ids.delete(@linear_interface.find_label(MIGRATION_IN_PROGRESS_LABEL_NAME_DRY_RUN))
+              linear_label_ids.append(@linear_interface.find_label(MIGRATION_LABEL_NAME_DRY_RUN))
+            else
+              linear_label_ids.delete(@linear_interface.find_label(MIGRATION_IN_PROGRESS_LABEL_NAME))
+              linear_label_ids.append(@linear_interface.find_label(MIGRATION_LABEL_NAME))
+            end
+            @linear_interface.update_labels(issue_id, linear_label_ids)
+          end
+
+          def determine_assignee_id(gitlab_issue)
+            (return unless gitlab_issue.resource[:assignees]&.length&.positive?
+
+             @linear_interface.get_user_id_by_email(gitlab_issue.resource[:assignees].first[:email])
+            )
+          end
+
+          def determine_state_id(gitlab_issue, linear_team_data, set_state)
+            if gitlab_issue.state == "closed"
+              find_state_id_by_name(linear_team_data, "Closed")
+            else
+              (find_state_id_by_name(linear_team_data, get_s_label(gitlab_issue.labels)) if set_state)
+            end
+          end
+
+          def determine_epic_id(gitlab_issue)
+            epic_id_in_linear = nil
+            if gitlab_issue.resource["epic"]
+              epic_id = gitlab_issue.resource["epic"]["id"]
+              epic_id_in_linear = get_linear_id_from_migration_map(gitlab_type: "epic", gitlab_id: epic_id)
+              epic_id_in_linear = @linear_interface.find_linear_issue_by_gitlab_url("#{gitlab_issue.host_url}#{gitlab_issue.resource["epic"]["url"]}") if epic_id_in_linear.nil?
+            end
+            epic_id_in_linear
+          end
+
+          def import_mr_links(gitlab_issue, linear_id)
+            gitlab_issue.related_merge_requests.each do |mr|
+              @linear_interface.create_mr_link(linear_id, mr.resource["web_url"], mr.project_path, mr.resource["iid"],
+                                               mr.resource["title"])
+            end
+          end
+
+          def get_linear_label_ids(gitlab_labels, team_id)
+            # 1. transform the labels ito a flat name list
+            # E::Level Easy --> Level Easy
+            # T::Bug --> Bug
+
+            gitlab_label_list = gitlab_labels.map { |n| n.name.gsub(/.*::/, "") }
+
+            if @gitlab_dry_run && !@linear_dry_run
+              gitlab_label_list.append(MIGRATION_IN_PROGRESS_LABEL_NAME_DRY_RUN)
+            else
+              gitlab_label_list.append(MIGRATION_IN_PROGRESS_LABEL_NAME)
+            end
+
+            # 2. list the labels in Linear
+
+            linear_labels = @linear_interface.list_labels(gitlab_label_list, team_id)
+
+            linear_labels["data"]["issueLabels"]["nodes"].map { |n| n["id"] }
+          end
+
+          def get_team_label(labels)
+            labels.select { |label| label.name.start_with?("#{@team_label_prefix}::") }
+                  .map { |label| label.name.split("::").last }
+                  .first
+          end
+
+          def get_s_label(labels)
+            labels.select { |label| label.name.start_with?("S::") }
+                  .map { |label| label.name.split("::").last }
+                  .first
+          end
+
+          def compile_migration_notes(gitlab_url, labels)
+            %(This issue was copied from GitLab by Triage Bot. Original issue: #{gitlab_url}
+
+Original labels: #{labels.map { |label| "'#{label.name}'" }.join(", ")}
+)
+          end
+
+          def find_state_id_by_name(teams, search_name)
+            return nil if teams.empty?
+
+            states = teams["states"]["nodes"]
+
+            # Finding the state with the given name
+            state = states.find { |s| s["name"] == LINEAR_STATE_MAP[search_name] }
+
+            # Return the id if state is found, otherwise nil
+            state["id"] unless state.nil?
+          end
+
+          def write_to_migration_map(gitlab_issue, linear_id: nil, linear_url: "")
+            gitlab_type = gitlab_issue.class.name.demodulize.underscore
+            gitlab_id = gitlab_issue.resource["id"]
+            gitlab_url = gitlab_issue.resource["web_url"]
+            linear_type = "issue"
+
+            @id_map.push(gitlab_type, gitlab_id, linear_type, linear_id, gitlab_url, linear_url)
+          end
+
+          def get_linear_id_from_migration_map(gitlab_type: "issue", gitlab_id: nil, linear_type: "issue")
+            row = @id_map.find do |element|
+              element[0] == gitlab_type && element[1] == gitlab_id && element[2] == linear_type
+            end
+            row[3] if row
+          end
+        end
+      end
+    end
+  end
+end

data/lib/gitlab/triage/linear/migrator/linear_interface.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+require_relative "graphql_client"
+
+module Gitlab
+  module Triage
+    module Linear
+      module Migrator
+        # An interface class that provides functions to get and send data from/to Linear
+        class LinearInterface
+          FIND_LABEL_QUERY = <<~GRAPHQL
+            query($label: String!) {
+              issueLabels(
+                filter: { name: { eq: $label } }
+              ) {
+                nodes {
+                  id
+                  name
+                }
+              }
+            }
+          GRAPHQL
+
+          UPDATE_LABELS_MUTATION = <<~GRAPHQL
+            mutation($issueId: String!, $labels: [String!]!) {
+              issueUpdate(input: { labelIds: $labels }, id: $issueId) {
+                lastSyncId
+                success
+              }
+            }
+          GRAPHQL
+
+          LIST_LABELS_QUERY = <<~GRAPHQL
+            query($labels: [String!], $teamId: ID) {
+              issueLabels(
+                filter: {
+                  name: { in: $labels }
+                  or: [
+                    { team: { id: { eq: $teamId } } }
+                    { team: { null: true } }
+                  ]
+                }
+              ) {
+                nodes {
+                  id
+                  name
+                }
+              }
+            }
+          GRAPHQL
+
+          GET_USER_ID_BY_EMAIL_QUERY = <<~GRAPHQL
+            query($email: String!) {
+              users(filter: { email: { eq: $email } }) {
+                nodes {
+                  id
+                }
+              }
+            }
+          GRAPHQL
+
+          GET_TEAM_BY_NAME_QUERY = <<~GRAPHQL
+            query($name: String!) {
+              teams(filter: { name: { eq: $name } }) {
+                nodes {
+                  id
+                  name
+                  states {
+                    nodes {
+                      id
+                      name
+                    }
+                  }
+                }
+              }
+            }
+          GRAPHQL
+
+          FIND_LINEAR_ISSUE_BY_GITLAB_URL_QUERY = <<~GRAPHQL
+            query($gitlabUrl: String!) {
+              issueSearch(
+                filter: {
+                  comments: {
+                    body: {
+                      contains: "Original issue: $gitlabUrl"
+                    }
+                  }
+                }
+              ) {
+                nodes {
+                  id
+                }
+              }
+            }
+          GRAPHQL
+
+          def initialize(graphql_client: GraphqlClient)
+            @graphql_client = graphql_client
+          end
+
+          def find_label(label)
+            response = @graphql_client.query(FIND_LABEL_QUERY, { label: })
+            response["data"]["issueLabels"]["nodes"].first["id"]
+          end
+
+          def update_labels(issue_id, labels)
+            @graphql_client.mutation(UPDATE_LABELS_MUTATION, { issueId: issue_id, labels: })
+          end
+
+          def list_labels(labels, team_id)
+            @graphql_client.query(LIST_LABELS_QUERY, { labels:, teamId: team_id })
+          end
+
+          def get_user_id_by_email(email)
+            return nil if email.nil? || email.empty?
+
+            response = @graphql_client.query(GET_USER_ID_BY_EMAIL_QUERY, { email: })
+            response["data"]["users"]["nodes"].first["id"]
+          end
+
+          def get_team_by_name(name)
+            response = @graphql_client.query(GET_TEAM_BY_NAME_QUERY, { name: })
+            raise StandardError, "Team #{name} not found in Linear." if response["data"]["teams"]["nodes"].empty?
+
+            response["data"]["teams"]["nodes"].first
+          end
+
+          def find_linear_issue_by_gitlab_url(gitlab_url)
+            response = @graphql_client.query(FIND_LINEAR_ISSUE_BY_GITLAB_URL_QUERY, { gitlabUrl: gitlab_url })
+            response["data"]["issueSearch"]["nodes"].first["id"]
+          end
+
+          def create_issue(issue_data)
+            query = build_graphql_mutation("issueCreate", {
+                                             input: {
+                                               title: issue_data[:title],
+                                               teamId: issue_data[:team_id],
+                                               description: issue_data[:description],
+                                               createAsUser: issue_data[:create_as_user],
+                                               assigneeId: issue_data[:assignee_id],
+                                               stateId: issue_data[:state_id],
+                                               parentId: issue_data[:parent_id],
+                                               createdAt: issue_data[:created_at],
+                                               labelIds: issue_data[:label_ids],
+                                               dueDate: issue_data[:due_date],
+                                               sortOrder: issue_data[:sort_order]
+                                             }
+                                           }, ["lastSyncId", "success", "issue { id, url }"])
+
+            linear_issue = @graphql_client.mutation(query)
+            linear_issue&.dig("data", "issueCreate", "issue")
+          end
+
+          def create_comment(body: "", linear_issue_id: nil, author_name: nil, parent_id: nil, created_at: Time.now)
+            query = build_graphql_mutation("commentCreate", {
+                                             input: {
+                                               body: body.gsub("...", ". . . "),
+                                               issueId: linear_issue_id,
+                                               parentId: parent_id,
+                                               createAsUser: author_name,
+                                               createdAt: created_at
+                                             }
+                                           }, ["lastSyncId", "success", "comment { id }"])
+
+            response = @graphql_client.mutation(query)
+            response["data"]["commentCreate"]["comment"]
+          end
+
+          def create_mr_link(linear_id, url, path, number, title)
+            query = build_graphql_mutation("attachmentLinkGitLabMR", {
+                                             issueId: linear_id,
+                                             url:,
+                                             projectPathWithNamespace: path,
+                                             number:,
+                                             title:
+                                           }, %w[lastSyncId success])
+
+            @graphql_client.mutation(query)
+          end
+
+          def create_url_link(linear_id, url, title = nil)
+            query = build_graphql_mutation("attachmentLinkURL", {
+                                             issueId: linear_id,
+                                             url:,
+                                             title:
+                                           }, %w[lastSyncId success])
+
+            @graphql_client.mutation(query)
+          end
+
+          private
+
+          def process_variables(vars)
+            vars.map do |key, value|
+              if value.is_a?(Hash)
+                inner_vars = process_variables(value)
+                "#{key}: { #{inner_vars} }"
+              else
+                "#{key}: #{value.to_json}"
+              end
+            end.join("\n")
+          end
+
+          def build_graphql_mutation(field, variables, return_fields)
+            variables_str = process_variables(variables)
+            return_fields_str = return_fields.join("\n")
+
+            <<~GRAPHQL
+              mutation {
+                #{field}(
+                  #{variables_str}
+                ) {
+                  #{return_fields_str}
+                }
+              }
+            GRAPHQL
+          end
+        end
+      end
+    end
+  end
+end

data/lib/gitlab/triage/linear/migrator/query_logger.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "rainbow"
+
+module Gitlab
+  module Triage
+    module Linear
+      module Migrator
+        # Provides functions to log a query or result to the output.
+        module QueryLogger
+          def log_query(query_string, variables)
+            puts Rainbow("Query: #{query_string}").cyan
+            puts Rainbow("Variables: #{variables}").yellow
+          end
+
+          def log_response(response)
+            puts Rainbow("Response: #{response}").green
+          end
+
+          def log_cache_hit(cache_key)
+            puts Rainbow("Cache hit for key: #{cache_key}").green
+          end
+
+          def log_dry_run(mutation_string, variables)
+            puts Rainbow("DRY-RUN:").blue
+            puts Rainbow(mutation_string).blue
+            puts Rainbow(variables).blue
+          end
+
+          def log_error(errors)
+            puts Rainbow("GraphQL Error: #{errors}").red
+          end
+        end
+      end
+    end
+  end
+end

data/lib/gitlab/triage/linear/migrator/version.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Gitlab
+  module Triage
+    module Linear
+      module Migrator
+        VERSION = "1.0.0.rc1"
+      end
+    end
+  end
+end

data/lib/gitlab/triage/linear/migrator.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative "migrator/version"
+
+module Gitlab
+  module Triage
+    module Linear
+      # Migrates issues from GitLab to Linear
+      module Migrator
+      end
+    end
+  end
+end

data/sig/gitlab/triage/linear/migrator.rbs

@@ -0,0 +1,10 @@
+module Gitlab
+  module Triage
+    module Linear
+      module Migrator
+        VERSION: String
+        # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+      end
+    end
+  end
+end

data/support/.gitlab-ci.example.yml

@@ -0,0 +1,21 @@
+stages:
+  - triage
+
+migrate-to-linear:dry-run:
+  stage: triage
+  image: ruby:3.1
+  script:
+    - gem install gitlab-triage-linear-migrator
+    - gitlab-triage --dry-run --token $GITLAB_API_TOKEN --host-url $CI_SERVER_URL --source projects --source-id $CI_PROJECT_PATH --require ./triage_plugins.example.rb --policies-file 'triage_policies.example.yml'
+  when: manual
+  except:
+    - schedules
+
+migrate-to-linear:run:
+  stage: triage
+  image: ruby:3.1
+  script:
+    - gem install gitlab-triage-linear-migrator
+    - gitlab-triage --token $GITLAB_API_TOKEN --host-url $CI_SERVER_URL --source projects --source-id $CI_PROJECT_PATH --require ./triage_plugins.example.rb --policies-file 'triage_policies.example.yml'
+  only:
+    - schedules

data/support/triage_plugins.example.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require "gitlab/triage/linear/migrator/issue_extension"
+Gitlab::Triage::Resource::Context.include Gitlab::Triage::Linear::Migrator::IssueExtension

data/support/triage_policies.example.yml

@@ -0,0 +1,31 @@
+resource_rules:
+  issues:
+    rules:
+      - name: Create issue in Linear
+        limits:
+          most_recent: 500
+        conditions:
+          labels:
+            - "Linear::To Migrate"  # Remove this line if you want all issues to be migrated.
+          #state: opened # Remove this if you want closed issues to be migrated as well.
+          forbidden_labels:
+            - "Linear::Migrated"
+            - "Linear::Migration Failed"
+          ruby: "!labels.map(&:name).grep(/^Guild::.+$/).empty?" # Change this to match team_label_prefix parameter below!
+        actions:
+          comment: |
+            #{create_issue_in_linear(set_state: true, prepend_project_name: false, team_label_prefix: "Guild")}
+
+          # Change the parameters as you wish:
+          #  - set_state: set to true if you want your imported issues reflect the current state (group label `S::` in GitLab).
+          #      Please note: issues in `S::Inbox` will be migrated to Triage if your team has Triage turned on in Linear.
+          #      If Triage is turned off, issues will have the default issue state, which is indicated (and can be set) on your
+          #      team's Workflow settings page in Linear.
+          #  - prepend_project_name: true means all imported issues will have their titles starting with the GitLab project name.
+          #    Set to false to simply copy the issue title as is.
+          #  - team_label_prefix: The migration requires a label in Gitlab that can be used to set the team name in Linear.
+          #    By default this label needs to be in this format `Team::Name of the team`. The team in Linear must be `Team: Name of the team`.
+          #    You can change the `Team:` prefix by setting this parameter to anything you want (e.g. Guild as in the example above).
+
+          # This comment action will post a comment with a link to the new issue in Linear, add Linear::Migrated label and close the issue.
+          # If the migration fails, it will add Linear::Migration Failed label and also some error debug information into the comment.

metadata

@@ -0,0 +1,106 @@
+--- !ruby/object:Gem::Specification
+name: gitlab-triage-linear-migrator
+version: !ruby/object:Gem::Version
+  version: 1.0.0.rc1
+platform: ruby
+authors:
+- Laurent Arnoud
+- Roland Molnár
+bindir: exe
+cert_chain: []
+date: 2025-02-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: gitlab
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.19'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.19'
+- !ruby/object:Gem::Dependency
+  name: gitlab-triage
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.42'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.42'
+- !ruby/object:Gem::Dependency
+  name: rainbow
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Extends GitLab Triage Bot with actions to import issues into Linear (https://linear.app).
+  Initial version was developed by Platform.sh
+email:
+- laurent.arnoud@platform.sh
+- roland.molnar@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/gitlab/triage/linear/migrator.rb
+- lib/gitlab/triage/linear/migrator/graphql_client.rb
+- lib/gitlab/triage/linear/migrator/issue_extension.rb
+- lib/gitlab/triage/linear/migrator/linear_connector.rb
+- lib/gitlab/triage/linear/migrator/linear_interface.rb
+- lib/gitlab/triage/linear/migrator/query_logger.rb
+- lib/gitlab/triage/linear/migrator/version.rb
+- sig/gitlab/triage/linear/migrator.rbs
+- support/.gitlab-ci.example.yml
+- support/triage_plugins.example.rb
+- support/triage_policies.example.yml
+homepage: https://github.com/upsun/gitlab-triage-linear-migrator
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/upsun/gitlab-triage-linear-migrator
+  source_code_uri: https://github.com/upsun/gitlab-triage-linear-migrator
+  changelog_uri: https://github.com/upsun/gitlab-triage-linear-migrator
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Triage Bot extension to migrate GitLab issues to Linear.
+test_files: []