Class: PlanMyStuff::Issue

Overview

Wraps a GitHub issue with parsed PMS metadata and comments. Class methods provide the public API for CRUD operations.

Follows an ActiveRecord-style pattern:

  • ‘Issue.new(**attrs)` creates an unpersisted instance

  • ‘Issue.create!` / `Issue.find` / `Issue.list` return persisted instances

  • ‘issue.save!` / `issue.update!` / `issue.reload` for persistence

Instance Attribute Summary

Attributes inherited from ApplicationRecord

#github_response

Class Method Summary collapse

Instance Method Summary collapse

Methods included from PlanMyStuff::IssueExtractions::Waiting

#clear_waiting_on_user!, #enter_waiting_on_user!, #reopen_by_reply!

Methods included from PlanMyStuff::IssueExtractions::Viewers

#add_viewers!, #remove_viewers!, #visible_to?

Methods included from PlanMyStuff::IssueExtractions::Links

#add_blocker!, #add_related!, #add_sub_issue!, #blocked_by, #blocking, #duplicate_of, #mark_duplicate!, #parent, #related, #remove_blocker!, #remove_parent!, #remove_related!, #remove_sub_issue!, #set_parent!, #sub_tickets

Methods included from PlanMyStuff::IssueExtractions::Approvals

#approvals_required?, #approve!, #approvers, #fully_approved?, #pending_approvals, #reject!, #rejected_approvals, #remove_approvers!, #request_approvals!, #revoke_approval!

Methods inherited from ApplicationRecord

#destroyed?, #new_record?, #persisted?, read_field

Constructor Details

#initialize(**attrs) ⇒ Issue

Returns a new instance of Issue.



466
467
468
469
# File 'lib/plan_my_stuff/issue.rb', line 466

def initialize(**attrs)
  @body_dirty = false
  super
end

Class Method Details

.check_import!(import_id, repo: nil) ⇒ Hash

Polls a previously-submitted import for its current status.

Parameters:

  • import_id (Integer)

    id from the Issue.import response

  • repo (Symbol, String, nil) (defaults to: nil)

    defaults to config.default_repo

Returns:

  • (Hash)

    parsed status response

Raises:



343
344
345
346
347
348
349
350
351
352
353
# File 'lib/plan_my_stuff/issue.rb', line 343

def check_import!(import_id, repo: nil)
  client = PlanMyStuff.import_client
  resolved_repo = client.resolve_repo!(repo)

  client.octokit.get(
    "/repos/#{resolved_repo}/import/issues/#{import_id}",
    accept: 'application/vnd.github.golden-comet-preview+json',
  )
rescue Octokit::ClientError, Octokit::ServerError => e
  raise(PlanMyStuff::APIError.new(e.message, status: e.respond_to?(:response_status) ? e.response_status : nil))
end

.create!(title:, body:, repo: nil, labels: [], user: nil, metadata: {}, add_to_project: nil, visibility: 'public', visibility_allowlist: [], issue_type: nil, attachments: []) ⇒ PlanMyStuff::Issue

Creates a GitHub issue with PMS metadata embedded in the body.

Parameters:

  • title (String)
  • body (String)
  • repo (Symbol, String, nil) (defaults to: nil)

    defaults to config.default_repo

  • labels (Array<String>) (defaults to: [])
  • user (Object, Integer) (defaults to: nil)

    user object or user_id

  • metadata (Hash) (defaults to: {})

    custom fields hash

  • add_to_project (Boolean, Integer, nil) (defaults to: nil)
  • visibility (String) (defaults to: 'public')

    “public” or “internal”

  • visibility_allowlist (Array<Integer>) (defaults to: [])

    user IDs for internal comment access

  • issue_type (String, nil) (defaults to: nil)

    GitHub issue type name (e.g. “Bug”, “Feature”). Must match a type configured on the org. nil creates the issue with no type.

  • attachments (Array) (defaults to: [])

    files to upload to config.attachment_repo and record on the body comment. Each entry may be an uploaded-file object responding to #path and #original_filename (e.g. Rails ActionDispatch::Http::UploadedFile), a String/Pathname path to a local file, or a pre-built PlanMyStuff::Attachment instance (passthrough, no re-upload). Forwarded to the body comment’s attachments: kwarg; see Comment.create! for full detail.

Returns:

Raises:



95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
# File 'lib/plan_my_stuff/issue.rb', line 95

def create!(
  title:,
  body:,
  repo: nil,
  labels: [],
  user: nil,
  metadata: {},
  add_to_project: nil,
  visibility: 'public',
  visibility_allowlist: [],
  issue_type: nil,
  attachments: []
)
  if body.blank?
    raise(PlanMyStuff::ValidationError.new('body must be present', field: :body, expected_type: :string))
  end

  client = PlanMyStuff.client
  resolved_repo = client.resolve_repo!(repo)

   = PlanMyStuff::IssueMetadata.build(
    user: user,
    visibility: visibility,
    custom_fields: ,
  )
  .visibility_allowlist = Array.wrap(visibility_allowlist)
  .validate_custom_fields!

  serialized_body = PlanMyStuff::MetadataParser.serialize!(.to_h, '')

  resolved_type = resolve_issue_type!(issue_type)

  options = {}
  options[:labels] = labels if labels.present?
  options[:type] = resolved_type if resolved_type.present?

  result = client.rest(:create_issue, resolved_repo, title, serialized_body, **options)
  number = read_field(result, :number)
  store_etag_to_cache(client, resolved_repo, number, result, cache_writer: :write_issue)

  link_body = visible_body_for(number, resolved_repo)
  if link_body.present?
    result = client.rest(
      :update_issue,
      resolved_repo,
      number,
      body: PlanMyStuff::MetadataParser.serialize!(.to_h, link_body),
    )
    store_etag_to_cache(client, resolved_repo, number, result, cache_writer: :write_issue)
  end

  issue = find(number, repo: resolved_repo)

  if add_to_project.present?
    project_number = resolve_project_number!(add_to_project)
    PlanMyStuff::ProjectItem.create!(issue, project_number: project_number)
  end

  PlanMyStuff::Comment.create!(
    issue: issue,
    body: body,
    user: user,
    visibility: .visibility.to_sym,
    skip_responded: true,
    issue_body: true,
    attachments: attachments,
  )

  issue.reload
  PlanMyStuff::Notifications.instrument('issue.created', issue, user: user)
  issue
end

.find(number, repo: nil) ⇒ PlanMyStuff::Issue

Finds a single GitHub issue by number and parses its PMS metadata.

Parameters:

  • number (Integer)
  • repo (Symbol, String, nil) (defaults to: nil)

    defaults to config.default_repo

Returns:

Raises:

  • (Octokit::NotFound)

    when the issue number resolves to a pull request



255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
# File 'lib/plan_my_stuff/issue.rb', line 255

def find(number, repo: nil)
  client = PlanMyStuff.client
  resolved_repo = client.resolve_repo!(repo)

  github_issue =
    fetch_with_etag_cache(
      client,
      resolved_repo,
      number,
      rest_method: :issue,
      cache_reader: :read_issue,
      cache_writer: :write_issue,
    )

  pull_request =
    if github_issue.respond_to?(:pull_request)
      github_issue.pull_request
    elsif github_issue.is_a?(Hash)
      github_issue[:pull_request] || github_issue['pull_request']
    end

  if pull_request
    raise(Octokit::NotFound, { method: 'GET', url: "repos/#{resolved_repo}/issues/#{number}" })
  end

  build(github_issue, repo: resolved_repo)
end

.import!(payloads) ⇒ Array<Hash>

Submits one or more pre-built payloads to GitHub’s “Import Issues” preview endpoint (+POST /repos/:repo/import/issues+). One request per payload: the endpoint only accepts a single {issue:, comments:} payload at a time.

Each payload hash MUST include a :repo key (symbol, string, or PlanMyStuff::Repo) and the GitHub-shaped :issue /+ :comments+ keys; :repo is extracted before the POST. Payloads are passed through to GitHub unchanged otherwise - callers are responsible for shape, encoding, and any PlanMyStuff metadata they want to embed.

The endpoint is async: each response carries an id and url for polling via Issue.check_import.

Parameters:

  • payloads (Array<Hash>, Hash)

Returns:

  • (Array<Hash>)

    one parsed status hash per input payload, in input order

Raises:

  • (ArgumentError)

    when the import payload is missing :repo



322
323
324
325
326
327
328
329
330
331
332
# File 'lib/plan_my_stuff/issue.rb', line 322

def import!(payloads)
  client = PlanMyStuff.import_client

  Array.wrap(payloads).map do |payload|
    repo = payload[:repo] || payload['repo'] || PlanMyStuff.configuration.default_repo
    raise(ArgumentError, 'import payload must include :repo') if repo.blank?

    body = payload.except(:repo, 'repo')
    submit_import_request!(client, client.resolve_repo!(repo), body)
  end
end

.list(repo: nil, state: :open, labels: [], page: 1, per_page: 25) ⇒ Array<PlanMyStuff::Issue>

Lists GitHub issues with optional filters and pagination.

Parameters:

  • repo (Symbol, String, nil) (defaults to: nil)

    defaults to config.default_repo

  • state (Symbol) (defaults to: :open)

    :open, :closed, or :all

  • labels (Array<String>) (defaults to: [])
  • page (Integer) (defaults to: 1)
  • per_page (Integer) (defaults to: 25)

Returns:



293
294
295
296
297
298
299
300
301
302
303
# File 'lib/plan_my_stuff/issue.rb', line 293

def list(repo: nil, state: :open, labels: [], page: 1, per_page: 25)
  client = PlanMyStuff.client
  resolved_repo = client.resolve_repo!(repo)

  params = { state: state.to_s, page: page, per_page: per_page }
  params[:labels] = labels.sort.join(',') if labels.present?

  github_issues = client.rest(:list_issues, resolved_repo, **params)
  filtered = github_issues.reject { |gi| gi.respond_to?(:pull_request) && gi.pull_request }
  filtered.map { |gi| build(gi, repo: resolved_repo) }
end

.update!(number:, repo: nil, title: nil, body: nil, metadata: nil, labels: nil, state: nil, assignees: nil, issue_type: ISSUE_TYPE_UNCHANGED) ⇒ Object

Updates an existing GitHub issue.

metadata: accepts either:

  • a PlanMyStuff::IssueMetadata instance - treated as the full authoritative metadata and serialized as-is (used by instance save!/update! so local @metadata mutations like metadata.commit_sha = … actually persist).

  • a Hash - patch-style merge against the CURRENT remote metadata. Top-level keys are merged in; :custom_fields is merged separately so unrelated fields stay intact.

Parameters:

  • number (Integer)
  • repo (Symbol, String, nil) (defaults to: nil)

    defaults to config.default_repo

  • title (String, nil) (defaults to: nil)
  • body (String, nil) (defaults to: nil)
  • metadata (PlanMyStuff::IssueMetadata, Hash, nil) (defaults to: nil)
  • labels (Array<String>, nil) (defaults to: nil)
  • state (Symbol, nil) (defaults to: nil)

    :open or :closed

  • assignees (Array<String>, String, nil) (defaults to: nil)

    GitHub logins

  • issue_type (String, nil) (defaults to: ISSUE_TYPE_UNCHANGED)

    GitHub issue type name. Pass a String to set, nil to clear, or omit the kwarg to leave the current type untouched. (nil-vs-omitted is differentiated by the private ISSUE_TYPE_UNCHANGED sentinel.)

Returns:

  • (Object)


193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
# File 'lib/plan_my_stuff/issue.rb', line 193

def update!(
  number:,
  repo: nil,
  title: nil,
  body: nil,
  metadata: nil,
  labels: nil,
  state: nil,
  assignees: nil,
  issue_type: ISSUE_TYPE_UNCHANGED
)
  client = PlanMyStuff.client
  resolved_repo = client.resolve_repo!(repo)

  options = {}
  options[:title] = title unless title.nil?
  options[:labels] = labels unless labels.nil?
  options[:state] = state.to_s unless state.nil?
  options[:assignees] = Array.wrap(assignees) unless assignees.nil?
  options[:type] = resolve_issue_type!(issue_type) unless issue_type.equal?(ISSUE_TYPE_UNCHANGED)

  case 
  when PlanMyStuff::IssueMetadata
    .validate_custom_fields!
    options[:body] =
      PlanMyStuff::MetadataParser.serialize!(.to_h, visible_body_for(number, resolved_repo))
  when Hash
    current = client.rest(:issue, resolved_repo, number)
    current_body = current.respond_to?(:body) ? current.body : current[:body]
    parsed = PlanMyStuff::MetadataParser.parse(current_body)
     = parsed[:metadata]

    merged_custom_fields = ([:custom_fields] || {}).merge([:custom_fields] || {})
     = .merge()
    [:custom_fields] = merged_custom_fields
    PlanMyStuff::CustomFields.new(
      PlanMyStuff.configuration.custom_fields_for(:issue),
      merged_custom_fields,
    ).validate!

    options[:body] =
      PlanMyStuff::MetadataParser.serialize!(, visible_body_for(number, resolved_repo))
  end

  update_body_comment!(number, resolved_repo, body) if body

  return if options.none?

  result = client.rest(:update_issue, resolved_repo, number, **options)
  store_etag_to_cache(client, resolved_repo, number, result, cache_writer: :write_issue)
  result
end

Instance Method Details

#archive!(now: Time.now.utc) ⇒ self

Tags the issue with the configured archived_label, removes it from every Projects V2 board it belongs to, locks its conversation on GitHub, and stamps metadata.archived_at. Emits plan_my_stuff.issue.archived on success.

No-op (no network calls, no event) when the issue is already archived (either metadata.archived_at is set or the archived label is already on the issue).

Parameters:

  • now (Time) (defaults to: Time.now.utc)

    clock reference for metadata.archived_at

Returns:

  • (self)


512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
# File 'lib/plan_my_stuff/issue.rb', line 512

def archive!(now: Time.now.utc)
  label = PlanMyStuff.configuration.archived_label
  return self unless state == 'closed'

  return self if .archived_at.present?
  return self if labels.include?(label)

  self.class.update!(
    number: number,
    repo: repo,
    metadata: { archived_at: PlanMyStuff.format_time(now) },
  )

  PlanMyStuff::Label.ensure!(repo: repo, name: label)
  PlanMyStuff::Label.add!(issue: self, labels: [label])

  remove_from_all_projects!

  PlanMyStuff.client.rest(:lock_issue, repo.full_name, number)

  reload

  PlanMyStuff::Notifications.instrument(
    'issue.archived',
    self,
    reason: :aged_closed,
  )
  self
end

#assigneesArray<String>

GitHub assignees for this issue, by login.

Returns:

  • (Array<String>)


614
615
616
# File 'lib/plan_my_stuff/issue.rb', line 614

def assignees
  extract_assignee_logins(github_response)
end

#bodyString?

Returns the issue body content. For PMS issues, this is the body from the body comment (stripped of its header). Falls back to the parsed issue body for non-PMS issues.

Returns:

  • (String, nil)


46
# File 'lib/plan_my_stuff/issue.rb', line 46

attribute :body, :string

#body=(value) ⇒ String

Assigning a new body marks the instance dirty so the next save! rewrites the backing PMS body comment. Unsaved assignments are reflected by #body until persisted or reloaded.

Parameters:

  • value (String)

Returns:

  • (String)


483
484
485
486
# File 'lib/plan_my_stuff/issue.rb', line 483

def body=(value)
  super
  @body_dirty = true
end

#body_commentPlanMyStuff::Comment?

Returns the comment marked as the issue body, if any.

Returns:



632
633
634
# File 'lib/plan_my_stuff/issue.rb', line 632

def body_comment
  pms_comments.find { |c| c..issue_body? }
end

#closed_atTime?

Returns GitHub’s closed_at timestamp (nil while open).

Returns:

  • (Time, nil)

    GitHub’s closed_at timestamp (nil while open)



39
# File 'lib/plan_my_stuff/issue.rb', line 39

attribute :closed_at

#commentsArray<PlanMyStuff::Comment>

Lazy-loads and memoizes comments from the GitHub API.

Returns:



598
599
600
# File 'lib/plan_my_stuff/issue.rb', line 598

def comments
  @comments ||= load_comments
end

#created_atTime?

Returns GitHub’s created_at timestamp; settable on unpersisted issues for use with Issue.import.

Returns:

  • (Time, nil)

    GitHub’s created_at timestamp; settable on unpersisted issues for use with Issue.import



37
# File 'lib/plan_my_stuff/issue.rb', line 37

attribute :created_at

#github_idInteger?

GitHub database ID (required for the REST issue-dependency API, which takes integer issue_id rather than issue number).

Returns:

  • (Integer, nil)


665
666
667
# File 'lib/plan_my_stuff/issue.rb', line 665

def github_id
  safe_read_field(github_response, :id)
end

#github_node_idString?

GitHub GraphQL node ID (required for native sub-issue mutations). Read from the hydrated REST response.

Returns:

  • (String, nil)


656
657
658
# File 'lib/plan_my_stuff/issue.rb', line 656

def github_node_id
  safe_read_field(github_response, :node_id)
end

#html_urlString?

GitHub web URL for this issue, for escape-hatch “View on GitHub” links.

Returns:

  • (String, nil)


606
607
608
# File 'lib/plan_my_stuff/issue.rb', line 606

def html_url
  safe_read_field(github_response, :html_url)
end

#issue_typeString?

Returns GitHub issue type name (e.g. “Bug”, “Feature”) or nil when no type is assigned. Read from the nested type.name field on the REST response. Settable via the issue_type: kwarg on Issue.create! / Issue.update!.

Returns:

  • (String, nil)

    GitHub issue type name (e.g. “Bug”, “Feature”) or nil when no type is assigned. Read from the nested type.name field on the REST response. Settable via the issue_type: kwarg on Issue.create! / Issue.update!.



50
# File 'lib/plan_my_stuff/issue.rb', line 50

attribute :issue_type, :string

#labelsArray<String>

Returns label names.

Returns:

  • (Array<String>)

    label names



33
# File 'lib/plan_my_stuff/issue.rb', line 33

attribute :labels, default: -> { [] }

#lockedBoolean Also known as: locked?

Returns GitHub’s locked flag; true for archived or manually-locked issues (no new comments).

Returns:

  • (Boolean)

    GitHub’s locked flag; true for archived or manually-locked issues (no new comments)



41
# File 'lib/plan_my_stuff/issue.rb', line 41

attribute :locked, :boolean, default: false

#metadataPlanMyStuff::IssueMetadata

Returns parsed metadata (empty when no PMS metadata present).

Returns:



27
# File 'lib/plan_my_stuff/issue.rb', line 27

attribute :metadata, default: -> { PlanMyStuff::IssueMetadata.new }

#numberInteger?

Returns GitHub issue number.

Returns:

  • (Integer, nil)

    GitHub issue number



23
# File 'lib/plan_my_stuff/issue.rb', line 23

attribute :number, :integer

#pms_commentsArray<PlanMyStuff::Comment>

Returns only comments created via PMS.

Returns:



624
625
626
# File 'lib/plan_my_stuff/issue.rb', line 624

def pms_comments
  comments.select(&:pms_comment?)
end

#pms_issue?Boolean

Returns:

  • (Boolean)


619
620
621
# File 'lib/plan_my_stuff/issue.rb', line 619

def pms_issue?
  .schema_version.present?
end

#raw_bodyString?

Returns full body as stored on GitHub.

Returns:

  • (String, nil)

    full body as stored on GitHub



25
# File 'lib/plan_my_stuff/issue.rb', line 25

attribute :raw_body, :string

#reloadself

Re-fetches this issue from GitHub and updates all local attributes.

Returns:

  • (self)


588
589
590
591
592
# File 'lib/plan_my_stuff/issue.rb', line 588

def reload
  fresh = self.class.find(number, repo: repo)
  hydrate_from_issue(fresh)
  self
end

#repoPlanMyStuff::Repo?

Returns:



44
# File 'lib/plan_my_stuff/issue.rb', line 44

attribute :repo

#repo=(value) ⇒ Object

Parameters:



472
473
474
# File 'lib/plan_my_stuff/issue.rb', line 472

def repo=(value)
  super(value.present? ? PlanMyStuff::Repo.resolve!(value) : nil)
end

#save!(user: nil, skip_notification: false) ⇒ self

Persists the issue. Creates if new, otherwise performs a full write: serializes @metadata into the GitHub issue body and PATCHes title/state/labels. When #body= has been called since the last load, also rewrites the PMS body comment. Always reloads afterwards.

Returns:

  • (self)


548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
# File 'lib/plan_my_stuff/issue.rb', line 548

def save!(user: nil, skip_notification: false)
  if new_record?
    created = self.class.create!(
      title: title,
      body: body,
      repo: repo,
      labels: labels || [],
      user: user || .created_by,
      metadata: .custom_fields.to_h,
      visibility: .visibility,
      visibility_allowlist: Array.wrap(.visibility_allowlist),
      issue_type: issue_type,
    )
    hydrate_from_issue(created)
  else
    captured_changes = changes.dup
    persist_update!
    instrument_update(captured_changes, user) unless skip_notification
  end

  self
end

#stateString?

Returns issue state (“open” or “closed”).

Returns:

  • (String, nil)

    issue state (“open” or “closed”)



31
# File 'lib/plan_my_stuff/issue.rb', line 31

attribute :state, :string

#titleString?

Returns issue title.

Returns:

  • (String, nil)

    issue title



29
# File 'lib/plan_my_stuff/issue.rb', line 29

attribute :title, :string

#update!(user: nil, skip_notification: false, **attrs) ⇒ self

Applies attrs to this instance in-memory then calls save!. Supports title:, body:, state:, labels:, assignees:, and metadata:. The metadata: kwarg is a hash whose keys are merged into the existing metadata (top-level attributes assigned directly; :custom_fields merged key-by-key).

Parameters:

  • user (Object, nil) (defaults to: nil)

    actor for notification events

Returns:

  • (self)


579
580
581
582
# File 'lib/plan_my_stuff/issue.rb', line 579

def update!(user: nil, skip_notification: false, **attrs)
  apply_update_attrs(attrs)
  save!(user: user, skip_notification: skip_notification)
end

#updated_atTime?

Returns GitHub’s updated_at timestamp.

Returns:

  • (Time, nil)

    GitHub’s updated_at timestamp



35
# File 'lib/plan_my_stuff/issue.rb', line 35

attribute :updated_at

Returns per-issue URL in the consuming app (config.issues_url_prefix + “/” + number + “?repo=Org/Repo”, or nil when either prefix or number is missing). Also rendered as the destination of the markdown link in the GitHub issue body.

Returns:

  • (String, nil)

    per-issue URL in the consuming app (config.issues_url_prefix + “/” + number + “?repo=Org/Repo”, or nil when either prefix or number is missing). Also rendered as the destination of the markdown link in the GitHub issue body.



491
492
493
494
495
496
497
498
499
# File 'lib/plan_my_stuff/issue.rb', line 491

def user_link
  prefix = PlanMyStuff.configuration.issues_url_prefix
  return if prefix.blank? || number.blank?

  base = "#{prefix.to_s.chomp('/')}/#{number}"
  return base if repo.blank?

  "#{base}?repo=#{URI.encode_www_form_component(repo.full_name)}"
end