marlens-github-to-jira-comment 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3d2671f36558d94fbc4e03f4b9fb6d94f406cdaf5cdf0d450ccf97e921446fc9
+  data.tar.gz: dab9a7f4e03050178663e4471ed8646648b477d4a16b3800318492f1906e358b
+SHA512:
+  metadata.gz: d3420e1f18718e6a3024cca6019ba055754940473e9890740b417fb3b8003c980824051e06b9f06c72761cd7ef156276be77245969424c4515f0ea5fd5ebc515
+  data.tar.gz: 0cac0986612cb0f105d57d221e102474c595fbab3e743f937377647f01d957bd0970bfa39241cd00a41c2c18882964ea3bf953ae4801483a9bd3e4b2a1a3efeb

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marlen Brunner
+
+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,72 @@
+# GitHub to Jira Comment
+
+Small Ruby CLI/gem for copying a GitHub issue or pull request body into a Jira issue comment with rich Jira formatting.
+
+## Required contract
+
+Both source and destination are URLs, not shorthand tags:
+
+```bash
+github-to-jira-comment \
+  --github-url https://github.com/icefoganalytics/wrap/pull/405 \
+  --jira-url https://yg-hpw.atlassian.net/browse/WRAPX-388
+```
+
+Credentials come from environment variables. `JIRA_BASE_URL` is optional; the CLI derives it from `--jira-url` unless you override it.
+
+```bash
+GITHUB_TOKEN=...
+JIRA_EMAIL=...
+JIRA_API_TOKEN=...
+```
+
+## Install
+
+```ruby
+gem "marlens-github-to-jira-comment", "~> 0.1"
+```
+
+## CLI
+
+```bash
+github-to-jira-comment \
+  --github-url https://github.com/icefoganalytics/wrap/pull/405 \
+  --jira-url https://yg-hpw.atlassian.net/browse/WRAPX-388
+```
+
+## Release cycle
+
+1. Work from an issue branch and open a draft PR linked to the issue.
+2. Run `bundle exec rspec`, `bin/github-to-jira-comment --help`, and `gem build marlens-github-to-jira-comment.gemspec`.
+3. Delete the generated `.gem` file after the build check.
+4. Mark the PR ready, merge it to `main`, then update local `main`.
+5. Build the release artifact from `main` with `gem build marlens-github-to-jira-comment.gemspec`.
+6. Publish with `gem push marlens-github-to-jira-comment-<version>.gem`.
+7. Tag the release as `v<version>` and create the GitHub release.
+8. Verify RubyGems lists the version with `gem list --remote marlens-github-to-jira-comment --exact --all`.
+9. Install the published gem in a temporary `GEM_HOME` and smoke-check `github-to-jira-comment --help`.
+10. Delete the local `.gem` artifact after verification.
+
+## MVP scope
+
+1. Accept a full GitHub pull request URL or GitHub issue URL.
+2. Accept a full Jira issue URL.
+3. Fetch the GitHub title/body through the GitHub API.
+4. Convert/post the GitHub body to Jira using `marlens-jira-api`.
+5. Resolve real GitHub `user-attachments` images while preserving normal links and code blocks.
+6. Fail on image-upload degradation by using strict image handling.
+7. Return or print the created Jira comment ID.
+
+## Proved live example
+
+- GitHub source: https://github.com/icefoganalytics/wrap/pull/405
+- Jira destination: https://yg-hpw.atlassian.net/browse/WRAPX-388
+- Existing script-created Jira comment: `69213`
+- Created at: `2026-07-09T11:42:26.501-0700`
+- Verified markers:
+  - `Fixes https://yg-hpw.atlassian.net/browse/WRAPX-388` rendered as text + Jira link mark.
+  - `# Context` rendered as an ADF heading.
+  - numbered Implementation/Testing lists rendered as ordered lists.
+  - testing commands rendered as code marks.
+
+See `docs/HANDOFF.md` for implementation notes and source artifacts.

data/bin/github-to-jira-comment

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/marlens/github_to_jira_comment"
+
+exit(Marlens::GithubToJiraComment::CLI.run(ARGV))

data/lib/marlens/github_to_jira_comment/cli.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "optparse"
+require "marlens/jira_api"
+
+module Marlens
+  module GithubToJiraComment
+    class CLI
+      def self.run(argv = ARGV, env: ENV, out: $stdout, err: $stderr, github_client_factory: nil, jira_client_factory: nil)
+        new(env:, out:, err:, github_client_factory:, jira_client_factory:).call(argv)
+      end
+
+      def initialize(env: ENV, out: $stdout, err: $stderr, github_client_factory: nil, jira_client_factory: nil, markdown_resolver_factory: nil, comment_poster_factory: nil)
+        @env = env
+        @out = out
+        @err = err
+        @github_client_factory = github_client_factory
+        @jira_client_factory = jira_client_factory
+        @markdown_resolver_factory = markdown_resolver_factory
+        @comment_poster_factory = comment_poster_factory
+      end
+
+      def call(argv)
+        options = parse_options(argv.dup)
+        missing = %i[github_url jira_url].select { |key| options[key].to_s.empty? }
+        return fail_with("Missing required option(s): #{option_names(missing)}") unless missing.empty?
+
+        source = github_client.fetch(options.fetch(:github_url))
+        resolved = resolve_markdown(source.body, github_url: options.fetch(:github_url))
+        result = post_comment(options.fetch(:jira_url), resolved)
+
+        @out.puts(result.fetch("id") { result.fetch(:id) })
+        0
+      rescue ArgumentError, KeyError, OptionParser::ParseError, RuntimeError => error
+        fail_with(error.message)
+      end
+
+      private
+
+      ResolvedMarkdown = Struct.new(:markdown, :allowed_image_hosts, keyword_init: true)
+
+      def parse_options(argv)
+        options = {}
+        OptionParser.new do |parser|
+          parser.banner = "Usage: github-to-jira-comment --github-url URL --jira-url URL"
+          parser.on("--github-url URL", "GitHub pull request or issue URL") { |value| options[:github_url] = value }
+          parser.on("--jira-url URL", "Jira browse URL") { |value| options[:jira_url] = value }
+        end.parse!(argv)
+        options
+      end
+
+      def resolve_markdown(markdown, github_url:)
+        resolver = markdown_resolver
+        result = if resolver.respond_to?(:resolve_with_metadata)
+                   resolver.resolve_with_metadata(markdown, context: GithubUrl.parse(github_url).context)
+                 else
+                   resolver.resolve(markdown)
+                 end
+        result.respond_to?(:markdown) ? result : ResolvedMarkdown.new(markdown: result, allowed_image_hosts: CommentPoster::DEFAULT_IMAGE_HOSTS)
+      end
+
+      def post_comment(jira_url, resolved)
+        poster = comment_poster(jira_url)
+        options = {
+          jira_url:,
+          markdown: resolved.markdown,
+          allowed_image_hosts: resolved.allowed_image_hosts,
+        }
+        poster.post(**options)
+      end
+
+      def github_client
+        @github_client ||= @github_client_factory&.call || GithubClient.new(token: @env.fetch("GITHUB_TOKEN"))
+      end
+
+      def markdown_resolver
+        @markdown_resolver ||= @markdown_resolver_factory&.call || GithubMarkdownResolver.new(github_client: github_client)
+      end
+
+      def comment_poster(jira_url)
+        @comment_poster ||= @comment_poster_factory&.call || CommentPoster.new(jira_client: jira_client(jira_url))
+      end
+
+      def jira_client(jira_url)
+        jira_issue = JiraUrl.parse(jira_url)
+        return @jira_client_factory.call(env: @env, base_url: @env["JIRA_BASE_URL"] || jira_issue.base_url) if @jira_client_factory
+
+        Marlens::JiraApi::Client.new(
+          base_url: @env["JIRA_BASE_URL"] || jira_issue.base_url,
+          email: @env.fetch("JIRA_EMAIL"),
+          api_token: @env.fetch("JIRA_API_TOKEN")
+        )
+      end
+
+      def fail_with(message)
+        @err.puts(message)
+        1
+      end
+
+      def option_names(keys)
+        keys.map { |key| "--#{key.to_s.tr("_", "-")}" }.join(", ")
+      end
+    end
+  end
+end

data/lib/marlens/github_to_jira_comment/comment_poster.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Marlens
+  module GithubToJiraComment
+    class CommentPoster
+      DEFAULT_IMAGE_HOSTS = ["private-user-images.githubusercontent.com"].freeze
+
+      def initialize(jira_client:)
+        @jira_client = jira_client
+      end
+
+      def post(jira_url:, markdown:, allowed_image_hosts: DEFAULT_IMAGE_HOSTS)
+        create(
+          issue_key: JiraUrl.parse(jira_url).issue_key,
+          markdown:,
+          allowed_image_hosts:
+        )
+      end
+
+      def create(issue_key:, markdown:, allowed_image_hosts: [])
+        @jira_client.create_markdown_comment(
+          issue_key:,
+          markdown:,
+          allowed_image_hosts:,
+          strict_images: true,
+          image_upload_failures: []
+        )
+      end
+    end
+  end
+end

data/lib/marlens/github_to_jira_comment/github_client.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module Marlens
+  module GithubToJiraComment
+    class GithubClient
+      Content = Struct.new(:title, :body, keyword_init: true)
+
+      API_ROOT = "https://api.github.com"
+
+      def initialize(token:, http: nil, requester: nil)
+        @token = token
+        @http = http
+        @requester = requester || method(:request)
+      end
+
+      def fetch(source)
+        source = GithubUrl.parse(source) if source.is_a?(String)
+        json = get_json(source.api_path)
+        Content.new(title: json.fetch("title"), body: json["body"].to_s)
+      end
+
+      def render_markdown(markdown, context:)
+        uri = URI("#{API_ROOT}/markdown")
+        request = Net::HTTP::Post.new(uri)
+        request.body = JSON.dump("text" => markdown, "mode" => "gfm", "context" => context)
+        response = perform(uri, request)
+        return response.body if response.code.to_i.between?(200, 299)
+
+        raise "GitHub Markdown render failed: #{response.code} #{response.body}"
+      end
+
+      private
+
+      def get_json(path)
+        return @http.get(path, headers:) if @http
+
+        uri = URI("#{API_ROOT}#{path}")
+        response = perform(uri, Net::HTTP::Get.new(uri))
+        return JSON.parse(response.body) if response.code.to_i.between?(200, 299)
+
+        raise "GitHub API request failed: #{response.code} #{response.body}"
+      end
+
+      def perform(uri, request)
+        headers.each { |key, value| request[key] = value }
+        request["Content-Type"] = "application/json" if request.request_body_permitted?
+        @requester.call(uri, request)
+      end
+
+      def headers
+        {
+          "Accept" => "application/vnd.github+json",
+          "Authorization" => "Bearer #{@token}",
+        }
+      end
+
+      def request(uri, request)
+        Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https") do |http|
+          http.request(request)
+        end
+      end
+    end
+  end
+end

data/lib/marlens/github_to_jira_comment/github_markdown_resolver.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require "commonmarker"
+require "uri"
+
+module Marlens
+  module GithubToJiraComment
+    class GithubMarkdownResolver
+      Result = Struct.new(:markdown, :allowed_image_hosts, keyword_init: true)
+      Image = Struct.new(:url, keyword_init: true)
+
+      MARKDOWN_IMAGE = /!\[[^\]]*\]\(([^)\s]+)(\s+"[^"]*")?\)/
+      HTML_IMAGE = /<img\b(?<attributes>[^>]+)>/i
+
+      def initialize(github_client: nil, renderer: nil)
+        @github_client = github_client
+        @renderer = renderer
+      end
+
+      def resolve(markdown, context: nil)
+        resolve_with_metadata(markdown, context:).markdown
+      end
+
+      def resolve_with_metadata(markdown, context: nil)
+        images = image_occurrences(markdown)
+        attachment_images = images.select { |image| github_user_attachment?(image.url) }
+        return Result.new(markdown:, allowed_image_hosts: []) if attachment_images.empty?
+
+        rendered_images = rendered_image_urls(render_markdown(markdown, context:)).select { |url| rendered_attachment?(url) }
+        mappings = {}
+        attachment_images.each_with_index do |image, index|
+          rendered = rendered_images[index] || mappings[image.url]
+          raise "GitHub Markdown render did not return an image for #{image.url}" unless rendered
+
+          mappings[image.url] ||= rendered
+        end
+
+        resolved = rewrite_image_urls(markdown, mappings)
+        Result.new(markdown: resolved, allowed_image_hosts: mappings.values.filter_map { |url| host(url) }.uniq)
+      end
+
+      private
+
+      def render_markdown(markdown, context:)
+        return @renderer.render(markdown) if @renderer
+
+        @github_client.render_markdown(markdown, context:)
+      end
+
+      def image_occurrences(markdown)
+        images = []
+        collect_images(markdown_document(markdown), images)
+        images
+      end
+
+      def rewrite_image_urls(markdown, mappings)
+        fenced = false
+        markdown.each_line.map do |line|
+          if line.match?(/\A\s*(```|~~~)/)
+            fenced = !fenced
+            next line
+          end
+          next line if fenced
+
+          line
+            .gsub(MARKDOWN_IMAGE) { |match| mappings.key?($1) ? match.sub($1, mappings.fetch($1)) : match }
+            .gsub(HTML_IMAGE) { |match| rewrite_html_image(match, mappings) }
+        end.join
+      end
+
+      def rewrite_html_image(tag, mappings)
+        url = html_image_url(tag)
+        return tag unless mappings.key?(url)
+
+        tag.sub(url, mappings.fetch(url))
+      end
+
+      def collect_images(node, images)
+        case node.type
+        when :image
+          images << Image.new(url: node.url)
+        when :html_inline, :html_block
+          html_image_url(node.to_commonmark)&.then { |url| images << Image.new(url:) }
+        end
+
+        node.each { |child| collect_images(child, images) }
+      end
+
+      def markdown_document(markdown)
+        Commonmarker.parse(
+          markdown,
+          options: {
+            parse: { smart: true },
+            extension: { autolink: true, strikethrough: true, table: true, tagfilter: false },
+          }
+        )
+      end
+
+      def rendered_image_urls(html)
+        html.scan(HTML_IMAGE).filter_map do |match|
+          parse_html_attributes(match.first)["src"]
+        end
+      end
+
+      def html_image_url(html)
+        match = html.match(HTML_IMAGE)
+        return nil unless match
+
+        parse_html_attributes(match[:attributes])["src"]
+      end
+
+      def parse_html_attributes(attributes)
+        attributes.scan(/([a-zA-Z:-]+)=["']([^"']+)["']/).to_h
+      end
+
+
+      def rendered_attachment?(url)
+        uri = URI.parse(url)
+        uri.host == "private-user-images.githubusercontent.com" || github_user_attachment?(url)
+      rescue URI::InvalidURIError
+        false
+      end
+      def github_user_attachment?(url)
+        uri = URI.parse(url)
+        uri.scheme == "https" && uri.host == "github.com" && uri.path.start_with?("/user-attachments/assets/")
+      rescue URI::InvalidURIError
+        false
+      end
+
+      def host(url)
+        URI.parse(url).host
+      rescue URI::InvalidURIError
+        nil
+      end
+    end
+  end
+end

data/lib/marlens/github_to_jira_comment/github_url.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Marlens
+  module GithubToJiraComment
+    class GithubUrl
+      Source = Struct.new(:owner, :repo, :type, :number, keyword_init: true) do
+        def api_path
+          collection = type == "pull" ? "pulls" : "issues"
+          "/repos/#{owner}/#{repo}/#{collection}/#{number}"
+        end
+
+        def context
+          "#{owner}/#{repo}"
+        end
+      end
+
+      def self.parse(url)
+        uri = URI.parse(url)
+        segments = uri.path.split("/").reject(&:empty?)
+        unless uri.is_a?(URI::HTTPS) && uri.host == "github.com" && segments.length == 4
+          raise ArgumentError, "GitHub URL must be https://github.com/<owner>/<repo>/pull/<number> or /issues/<number>"
+        end
+
+        owner, repo, path_type, number = segments
+        unless %w[pull issues].include?(path_type) && number.match?(/\A\d+\z/)
+          raise ArgumentError, "GitHub URL must point to a pull request or issue number"
+        end
+
+        Source.new(owner:, repo:, type: path_type == "pull" ? "pull" : "issue", number:)
+      rescue URI::InvalidURIError
+        raise ArgumentError, "Invalid GitHub URL"
+      end
+    end
+  end
+end

data/lib/marlens/github_to_jira_comment/jira_url.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Marlens
+  module GithubToJiraComment
+    class JiraUrl
+      Issue = Struct.new(:base_url, :issue_key, keyword_init: true)
+
+      def self.parse(url)
+        uri = URI.parse(url)
+        match = uri.path.match(%r{\A/browse/([A-Z][A-Z0-9_]*-\d+)\z})
+        unless uri.is_a?(URI::HTTPS) && uri.host&.end_with?(".atlassian.net") && match
+          raise ArgumentError, "Jira URL must be https://<site>.atlassian.net/browse/<ISSUE-KEY>"
+        end
+
+        Issue.new(base_url: "#{uri.scheme}://#{uri.host}", issue_key: match[1])
+      rescue URI::InvalidURIError
+        raise ArgumentError, "Invalid Jira URL"
+      end
+    end
+  end
+end

data/lib/marlens/github_to_jira_comment/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Marlens
+  module GithubToJiraComment
+    VERSION = "0.1.0"
+  end
+end

data/lib/marlens/github_to_jira_comment.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative "github_to_jira_comment/version"
+require_relative "github_to_jira_comment/github_url"
+require_relative "github_to_jira_comment/jira_url"
+require_relative "github_to_jira_comment/github_client"
+require_relative "github_to_jira_comment/github_markdown_resolver"
+require_relative "github_to_jira_comment/comment_poster"
+require_relative "github_to_jira_comment/cli"
+
+module Marlens
+  module GithubToJiraComment
+  end
+end

metadata

@@ -0,0 +1,97 @@
+--- !ruby/object:Gem::Specification
+name: marlens-github-to-jira-comment
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Marlen Brunner
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: marlens-jira-api
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+- !ruby/object:Gem::Dependency
+  name: commonmarker
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+description: Small CLI/gem bridge from full GitHub issue/pull request URLs to full
+  Jira issue URLs.
+email:
+- klondike.marlen@gmail.com
+executables:
+- github-to-jira-comment
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- bin/github-to-jira-comment
+- lib/marlens/github_to_jira_comment.rb
+- lib/marlens/github_to_jira_comment/cli.rb
+- lib/marlens/github_to_jira_comment/comment_poster.rb
+- lib/marlens/github_to_jira_comment/github_client.rb
+- lib/marlens/github_to_jira_comment/github_markdown_resolver.rb
+- lib/marlens/github_to_jira_comment/github_url.rb
+- lib/marlens/github_to_jira_comment/jira_url.rb
+- lib/marlens/github_to_jira_comment/version.rb
+homepage: https://github.com/klondikemarlen/github-to-jira-comment
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/klondikemarlen/github-to-jira-comment
+  source_code_uri: https://github.com/klondikemarlen/github-to-jira-comment
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: Copy GitHub issue or pull request bodies into Jira comments.
+test_files: []