Skip to content

GitHubShareClient

Namespace Nfty.Core.Publish.Community in assembly Nfty.Core.

public sealed class GitHubShareClient

The GitHub REST calls sharing needs. The token goes only in the Authorization header of requests to the endpoints' API and uploads hosts: never to the published list, never into a message. Every failure leaves as a ShareRules sentence: GitHubAuthException for a refused token, CommunityException for the rest. A caller's own cancellation stays an OperationCanceledException.

Constructors

GitHubShareClient(HttpClient, string, CommunityEndpoints, TimeProvider?, TimeSpan?)

public GitHubShareClient(HttpClient http, string token, CommunityEndpoints endpoints, TimeProvider? time = null, TimeSpan? bodyTimeout = null);

Parameters

  • http (HttpClient) - The client every request goes through (not disposed here).
  • token (string) - The person's GitHub access token.
  • endpoints (CommunityEndpoints) - Where the gallery and GitHub live.
  • time (TimeProvider?) - The clock a rate-limit wait is measured against; tests inject one.
  • bodyTimeout (TimeSpan?) - How long a response body may take once its headers arrived (default 30 seconds).

Methods

CreateBranchAsync(string, string, string, string, CancellationToken)

public Task CreateBranchAsync(string owner, string repo, string branch, string fromSha, CancellationToken ct);

Makes a branch at a commit.

Parameters

  • owner (string) - The account that owns the repository.
  • repo (string) - The repository name.
  • branch (string) - The new branch name.
  • fromSha (string) - The commit the branch starts at.
  • ct (CancellationToken) - Cancels the request.

CreateReleaseAsync(string, string, string, string, CancellationToken)

public Task<GitHubRelease> CreateReleaseAsync(string owner, string repo, string tag, string name, CancellationToken ct);

Makes a published release on a new tag.

Parameters

  • owner (string) - The account that owns the repository.
  • repo (string) - The repository name.
  • tag (string) - The new tag the release is made on.
  • name (string) - The release title.
  • ct (CancellationToken) - Cancels the request.

Returns. The release GitHub made.

CreateRepoAsync(string, string, CancellationToken)

public Task<GitHubRepo> CreateRepoAsync(string name, string description, CancellationToken ct);

Makes a public repository for the signed-in account, with a first commit so it has a branch.

Parameters

  • name (string) - The new repository name.
  • description (string) - The repository description.
  • ct (CancellationToken) - Cancels the request.

Returns. The repository GitHub made.

DeleteAssetAsync(string, string, long, CancellationToken)

public Task DeleteAssetAsync(string owner, string repo, long assetId, CancellationToken ct);

Deletes one file attached to a release.

Parameters

  • owner (string) - The account that owns the repository.
  • repo (string) - The repository name.
  • assetId (long) - The id of the attached file.
  • ct (CancellationToken) - Cancels the request.

DeleteBranchAsync(string, string, string, CancellationToken)

public Task DeleteBranchAsync(string owner, string repo, string branch, CancellationToken ct);

Deletes a branch.

Parameters

  • owner (string) - The account that owns the repository.
  • repo (string) - The repository name.
  • branch (string) - The branch to delete.
  • ct (CancellationToken) - Cancels the request.

DeleteFileAsync(string, string, string, string, string, string, CancellationToken)

public Task DeleteFileAsync(string owner, string repo, string path, string sha, string message, string branch, CancellationToken ct);

Deletes a file at the blob SHA given.

Parameters

  • owner (string) - The account that owns the repository.
  • repo (string) - The repository name.
  • path (string) - The file path inside the repository.
  • sha (string) - The blob SHA being deleted.
  • message (string) - The commit message.
  • branch (string) - The branch to commit to.
  • ct (CancellationToken) - Cancels the request.

DeleteReleaseAsync(string, string, long, CancellationToken)

public Task DeleteReleaseAsync(string owner, string repo, long id, CancellationToken ct);

Deletes a release (its tag stays; see GitHubShareClient.DeleteTagAsync()).

Parameters

  • owner (string) - The account that owns the repository.
  • repo (string) - The repository name.
  • id (long) - The release id.
  • ct (CancellationToken) - Cancels the request.

DeleteRepoAsync(string, string, CancellationToken)

public Task DeleteRepoAsync(string owner, string name, CancellationToken ct);

Deletes a repository. Needs the delete_repo scope, which sharing does not ask for, so GitHub usually refuses; the only caller is a rollback that already treats a refusal as best effort.

Parameters

  • owner (string) - The account that owns the repository.
  • name (string) - The repository name.
  • ct (CancellationToken) - Cancels the request.

DeleteTagAsync(string, string, string, CancellationToken)

public Task DeleteTagAsync(string owner, string repo, string tag, CancellationToken ct);

Deletes a tag.

Parameters

  • owner (string) - The account that owns the repository.
  • repo (string) - The repository name.
  • tag (string) - The tag to delete.
  • ct (CancellationToken) - Cancels the request.

ForkAsync(string, CancellationToken)

public Task<GitHubRepo> ForkAsync(string galleryRepo, CancellationToken ct);

Forks the gallery into the signed-in account. GitHub answers with the existing fork when there already is one; a new fork may take a moment to become readable.

Parameters

  • galleryRepo (string) - The gallery as owner/name.
  • ct (CancellationToken) - Cancels the request.

Returns. The fork, which is the existing one when the account already has it.

GetBranchShaAsync(string, string, string, CancellationToken)

public Task<string> GetBranchShaAsync(string owner, string repo, string branch, CancellationToken ct);

The tip commit of a branch.

Parameters

  • owner (string) - The account that owns the repository.
  • repo (string) - The repository name.
  • branch (string) - The branch to look up.
  • ct (CancellationToken) - Cancels the request.

Returns. The SHA of the branch tip commit.

GetFileAsync(string, string, string, string, CancellationToken)

public Task<(byte[], string)?> GetFileAsync(string owner, string repo, string path, string branch, CancellationToken ct);

A file's bytes and blob SHA on a branch, or null when it is not there.

Parameters

  • owner (string) - The account that owns the repository.
  • repo (string) - The repository name.
  • path (string) - The file path inside the repository.
  • branch (string) - The branch to read from.
  • ct (CancellationToken) - Cancels the request.

Returns. The file bytes and blob SHA, or null when the file is not there.

GetIndexAsync(CancellationToken)

public Task<CommunityIndex> GetIndexAsync(CancellationToken ct);

The published list, fetched from the gallery's site WITHOUT the token.

Parameters

  • ct (CancellationToken) - Cancels the request.

Returns. The gallery list as published.

Exceptions

GetPullAsync(string, int, CancellationToken)

public Task<GitHubPull> GetPullAsync(string galleryRepo, int number, CancellationToken ct);

A pull request's state.

Parameters

  • galleryRepo (string) - The gallery as owner/name.
  • number (int) - The pull request number.
  • ct (CancellationToken) - Cancels the request.

Returns. The state of the pull request and whether it was merged.

GetPullCommentsAsync(string, int, CancellationToken)

public Task<IReadOnlyList<string>> GetPullCommentsAsync(string galleryRepo, int number, CancellationToken ct);

The text of a pull request's conversation comments written by the gallery's checks bot (CommunityEndpoints.ActionsBot); anyone else's comment is dropped, since anyone may comment on a pull request.

Parameters

  • galleryRepo (string) - The gallery as owner/name.
  • number (int) - The pull request number.
  • ct (CancellationToken) - Cancels the request.

Returns. The comment texts written by the checks bot.

GetRepoAsync(string, string, CancellationToken)

public Task<GitHubRepo?> GetRepoAsync(string owner, string name, CancellationToken ct);

A repository, or null when it does not exist.

Parameters

  • owner (string) - The account that owns the repository.
  • name (string) - The repository name.
  • ct (CancellationToken) - Cancels the request.

Returns. The repository, or null when it does not exist.

GetTreeAsync(string, string, string, CancellationToken)

public Task<IReadOnlyList<GitHubTreeItem>> GetTreeAsync(string owner, string repo, string branch, CancellationToken ct);

Every item of a branch's tree, recursively.

Parameters

  • owner (string) - The account that owns the repository.
  • repo (string) - The repository name.
  • branch (string) - The branch whose tree is read.
  • ct (CancellationToken) - Cancels the request.

Returns. Every file and folder item in the tree.

GetViewerAsync(CancellationToken)

public Task<GitHubUser> GetViewerAsync(CancellationToken ct);

The signed-in account.

Parameters

  • ct (CancellationToken) - Cancels the request.

Returns. The account the token signs in.

ListBranchesAsync(string, string, CancellationToken)

public Task<IReadOnlyList<string>> ListBranchesAsync(string owner, string repo, CancellationToken ct);

Branch names.

Parameters

  • owner (string) - The account that owns the repository.
  • repo (string) - The repository name.
  • ct (CancellationToken) - Cancels the request.

Returns. The branch names.

ListOpenPullEntriesAsync(CancellationToken)

public Task<IReadOnlyList<CommunityEntry>> ListOpenPullEntriesAsync(CancellationToken ct);

The entries carried by the gallery's open pull requests (added or changed entries/**/*.json files, read at each request's head commit through the API). Files that don't parse as an entry are skipped.

Parameters

  • ct (CancellationToken) - Cancels the request.

Returns. The entries the open pull requests carry.

ListReleasesAsync(string, string, CancellationToken)

public Task<IReadOnlyList<GitHubRelease>> ListReleasesAsync(string owner, string repo, CancellationToken ct);

The repository's releases with their files.

Parameters

  • owner (string) - The account that owns the repository.
  • repo (string) - The repository name.
  • ct (CancellationToken) - Cancels the request.

Returns. The releases, each with its attached files.

ListTagsAsync(string, string, CancellationToken)

public Task<IReadOnlyList<string>> ListTagsAsync(string owner, string repo, CancellationToken ct);

Tag names.

Parameters

  • owner (string) - The account that owns the repository.
  • repo (string) - The repository name.
  • ct (CancellationToken) - Cancels the request.

Returns. The tag names.

OpenPullAsync(string, string, string, string, CancellationToken)

public Task<int> OpenPullAsync(string galleryRepo, string head, string title, string body, CancellationToken ct);

Opens a pull request into the gallery's default branch; head is owner:branch.

Parameters

  • galleryRepo (string) - The gallery as owner/name.
  • head (string) - The branch to merge, as owner:branch.
  • title (string) - The pull request title.
  • body (string) - The pull request description.
  • ct (CancellationToken) - Cancels the request.

Returns. The number of the pull request opened.

PutFileAsync(string, string, string, byte[], string, string?, string, CancellationToken)

public Task PutFileAsync(string owner, string repo, string path, byte[] content, string message, string? sha, string branch, CancellationToken ct);

Creates a file, or replaces it when sha names the version being replaced.

Parameters

  • owner (string) - The account that owns the repository.
  • repo (string) - The repository name.
  • path (string) - The file path inside the repository.
  • content (byte[]) - The file bytes to write.
  • message (string) - The commit message.
  • sha (string?) - The blob SHA being replaced, or null to create a new file.
  • branch (string) - The branch to commit to.
  • ct (CancellationToken) - Cancels the request.

UploadAssetAsync(GitHubRelease, string, Stream, long, IProgress<long>?, CancellationToken)

public Task UploadAssetAsync(GitHubRelease release, string name, Stream content, long length, IProgress<long>? progress, CancellationToken ct);

Attaches a file to a release, streamed: the content is read from content as it is sent, never buffered, with Content-Length stated up front. Progress is the number of bytes sent so far.

Parameters

  • release (GitHubRelease) - The release to attach the file to.
  • name (string) - The file name the asset is given.
  • content (Stream) - The stream the bytes are read from.
  • length (long) - The exact number of bytes to send.
  • progress (IProgress<long>?) - Receives the bytes sent so far; may be null.
  • ct (CancellationToken) - Cancels the request.