GhEx.Issues (gh_ex v0.3.4)

Copy Markdown View Source

Convenience functions for the GitHub Issues REST API.

Each function is a thin wrapper over GhEx.REST that fills in the endpoint path. They return the same {:ok, body, meta} / {:error, reason} shape as GhEx.REST and pass opts through to Req, so :params, headers, and a Req.Test plug all work. For an endpoint without a wrapper, call GhEx.REST directly.

Summary

Functions

Adds up to 10 assignees without replacing the issue's existing assignees.

Adds labels to an issue. labels is a list of label names.

Creates an issue. attrs is the JSON body (title, body, labels, assignees, ...).

Creates a repository label. attrs requires name and color and may set description.

Gets a single issue by number.

Gets a repository label by name.

Lists issues in a repository. Use params: for state, labels, per_page, and the other query options.

Lists the labels defined for a repository.

Removes selected assignees without changing any other assignees.

Replaces every label on an issue. Pass an empty list to remove all labels.

Auto-paginates issues in a repository into a lazy Stream of individual issues, following Link: rel="next" (see GhEx.REST.stream/3).

Auto-paginates the comments on an issue into a lazy Stream.

Auto-paginates the labels defined for a repository into a lazy Stream.

Updates an issue. attrs may set title, body, state, labels, and so on.

Updates an issue or pull request comment.

Updates a repository label identified by its current name.

Types

number_ref()

@type number_ref() :: integer() | String.t()

Functions

add_assignees(client, owner, repo, number, assignees, opts \\ [])

@spec add_assignees(
  GhEx.Client.t(),
  String.t(),
  String.t(),
  number_ref(),
  [String.t()],
  keyword()
) :: GhEx.REST.result()

Adds up to 10 assignees without replacing the issue's existing assignees.

GitHub silently ignores users who cannot be assigned.

add_labels(client, owner, repo, number, labels, opts \\ [])

@spec add_labels(
  GhEx.Client.t(),
  String.t(),
  String.t(),
  number_ref(),
  [String.t()],
  keyword()
) ::
  GhEx.REST.result()

Adds labels to an issue. labels is a list of label names.

create(client, owner, repo, attrs, opts \\ [])

@spec create(GhEx.Client.t(), String.t(), String.t(), map(), keyword()) ::
  GhEx.REST.result()

Creates an issue. attrs is the JSON body (title, body, labels, assignees, ...).

create_comment(client, owner, repo, number, body, opts \\ [])

@spec create_comment(
  GhEx.Client.t(),
  String.t(),
  String.t(),
  number_ref(),
  String.t(),
  keyword()
) ::
  GhEx.REST.result()

Adds a comment to an issue.

create_label(client, owner, repo, attrs, opts \\ [])

@spec create_label(GhEx.Client.t(), String.t(), String.t(), map(), keyword()) ::
  GhEx.REST.result()

Creates a repository label. attrs requires name and color and may set description.

Creating an existing name returns GitHub's 422 already_exists validation error as a GhEx.Error. An additive reconciler can catch that error, update the existing label, and re-fetch the repository labels between passes to account for concurrent writers.

get(client, owner, repo, number, opts \\ [])

Gets a single issue by number.

get_label(client, owner, repo, name, opts \\ [])

@spec get_label(GhEx.Client.t(), String.t(), String.t(), String.t(), keyword()) ::
  GhEx.REST.result()

Gets a repository label by name.

The name is percent-encoded as one path segment, so spaces, slashes, and other reserved characters are safe to pass directly.

list(client, owner, repo, opts \\ [])

Lists issues in a repository. Use params: for state, labels, per_page, and the other query options.

list_comments(client, owner, repo, number, opts \\ [])

@spec list_comments(GhEx.Client.t(), String.t(), String.t(), number_ref(), keyword()) ::
  GhEx.REST.result()

Lists the comments on an issue.

list_labels(client, owner, repo, opts \\ [])

@spec list_labels(GhEx.Client.t(), String.t(), String.t(), keyword()) ::
  GhEx.REST.result()

Lists the labels defined for a repository.

remove_assignees(client, owner, repo, number, assignees, opts \\ [])

@spec remove_assignees(
  GhEx.Client.t(),
  String.t(),
  String.t(),
  number_ref(),
  [String.t()],
  keyword()
) :: GhEx.REST.result()

Removes selected assignees without changing any other assignees.

remove_label(client, owner, repo, number, name, opts \\ [])

@spec remove_label(
  GhEx.Client.t(),
  String.t(),
  String.t(),
  number_ref(),
  String.t(),
  keyword()
) :: GhEx.REST.result()

Removes one label from an issue.

Label names are percent-encoded as a single path segment, so names containing spaces, slashes, or other reserved characters are safe to pass directly.

replace_all_labels(client, owner, repo, number, labels, opts \\ [])

@spec replace_all_labels(
  GhEx.Client.t(),
  String.t(),
  String.t(),
  number_ref(),
  [String.t()],
  keyword()
) :: GhEx.REST.result()

Replaces every label on an issue. Pass an empty list to remove all labels.

stream(client, owner, repo, opts \\ [])

@spec stream(GhEx.Client.t(), String.t(), String.t(), keyword()) :: Enumerable.t()

Auto-paginates issues in a repository into a lazy Stream of individual issues, following Link: rel="next" (see GhEx.REST.stream/3).

stream_comments(client, owner, repo, number, opts \\ [])

@spec stream_comments(
  GhEx.Client.t(),
  String.t(),
  String.t(),
  number_ref(),
  keyword()
) ::
  Enumerable.t()

Auto-paginates the comments on an issue into a lazy Stream.

stream_labels(client, owner, repo, opts \\ [])

@spec stream_labels(GhEx.Client.t(), String.t(), String.t(), keyword()) ::
  Enumerable.t()

Auto-paginates the labels defined for a repository into a lazy Stream.

update(client, owner, repo, number, attrs, opts \\ [])

@spec update(GhEx.Client.t(), String.t(), String.t(), number_ref(), map(), keyword()) ::
  GhEx.REST.result()

Updates an issue. attrs may set title, body, state, labels, and so on.

update_comment(client, owner, repo, comment_id, body, opts \\ [])

@spec update_comment(
  GhEx.Client.t(),
  String.t(),
  String.t(),
  number_ref(),
  String.t(),
  keyword()
) :: GhEx.REST.result()

Updates an issue or pull request comment.

Useful for rolling status comments that should be edited in place instead of creating a new comment on every update.

update_label(client, owner, repo, name, attrs, opts \\ [])

@spec update_label(
  GhEx.Client.t(),
  String.t(),
  String.t(),
  String.t(),
  map(),
  keyword()
) :: GhEx.REST.result()

Updates a repository label identified by its current name.

attrs may set new_name, color, and description. The current name is percent-encoded as one path segment.