Class GitHubRepo

Wraps a Octokit.GitHubClient and LibGit2Sharp.Repository into a single object that provides easy to use high-level methods while also including properties for the GitHub server, remote GitHub repository, as well as the local git repository,

note

GitHubRepo implements IDisposable and instances should be disposed when you're done with them.

Inheritance

object

GitHubRepo

Namespace: Neon.GitHub

Assembly: Neon.GitHub.dll

Syntax

public class GitHubRepo

Remarks

To clone a GitHub repository, call the static CloneAsync(string, string, string, string, string, string, string, string, IProfileClient) method, passing the GitHub repository path, path the the local folder and optionally the branch to be checked out as well as the GitHub credentials. This returns the GitHubRepo that you'll use for subsequent operations.

To manage a GitHub repository that doesn't have a local clone, call ConnectAsync(string, string, string, string, string, string, IProfileClient).

To open an existing local repository, call OpenAsync(string, string, string, string, string, string, IProfileClient).

To perform only GitHub account operations Call the static ConnectAsync(string, string, string, string, string, string, IProfileClient) method to construct an instance without a local repository reference.

The Local property provides some easy-to-use methods for managing the associated local git repository.

The Remote property provides some easy-to-use methods for managing the associated GitHub repository. These implement some common operations and are easier to use than the stock Octokit implementations.

The lower-level GitHubApi can be used to manage GitHub assets directly and GitApi is the lower-level API that can be used to manage the local git repository.

Properties

Credentials

Returns the associated GitHub credentials.

Declaration

public GitHubCredentials Credentials { get; set; }

Property Value

Type	Description
GitHubCredentials

Exceptions

Type	Condition
ObjectDisposedException	Thrown when the instance is disposed.

GitApi

Returns the lower level LibGit2Sharp.Repository API for managing the associated local git repository.

Declaration

public Repository GitApi { get; set; }

Property Value

Type	Description
Repository

Exceptions

Type	Condition
ObjectDisposedException	Thrown when the instance is disposed.
NoLocalRepositoryException	Thrown when the GitHubRepo is not associated with a local git repository.

GitHubApi

Returns the lower-level OctoKit Octokit.GitHubClient API that can be used to manage GitGub assets.

Declaration

public GitHubClient GitHubApi { get; set; }

Property Value

Type	Description
GitHubClient

Exceptions

Type	Condition
ObjectDisposedException	Thrown when the instance is disposed.

Local

Returns the friendly API methods used to manage the local git repository.

Declaration

public LocalRepoApi Local { get; set; }

Property Value

Type	Description
LocalRepoApi

Exceptions

Type	Condition
ObjectDisposedException	Thrown when the instance is disposed.
NoLocalRepositoryException	Thrown when the GitHubRepo is not associated with a local git repository.

Name

Returns the respository name.

Declaration

public string Name { get; }

Property Value

Type	Description
string

Origin

Returns the repository's remote GitHub remote origin.

Declaration

public Remote Origin { get; }

Property Value

Type	Description
Remote

Exceptions

Type	Condition
ObjectDisposedException	Thrown when the instance is disposed.
NoLocalRepositoryException	Thrown when the GitHubRepo is not associated with a local git repository.
LibGit2SharpException	Thrown if the repository doesn't have a remote origin.

Remote

Returns the friendly API methods used to manage the remote GitHub repository.

Declaration

public RemoteRepoApi Remote { get; set; }

Property Value

Type	Description
RemoteRepoApi

Exceptions

Type	Condition
ObjectDisposedException	Thrown when the instance is disposed.
NoLocalRepositoryException	Thrown when the GitHubRepo is not associated with a local git repository.

Methods

CloneAsync(string, string, string, string, string, string, string, string, IProfileClient)

Clones a GitHub repository to a local folder.

Declaration

public static Task<GitHubRepo> CloneAsync(string remoteRepoPath, string localRepoFolder, string branchName = null, string username = null, string accessToken = null, string password = null, string email = null, string userAgent = null, IProfileClient profileClient = null)

Parameters

Type	Name	Description
string	remoteRepoPath	Specifies the GitHub remote repository path, like: [SERVER/]OWNER/REPO or [SERVER/]OWNER/REPO-git. You may also include the ".git" suffix if desired, but this is optional.
string	localRepoFolder	Specifies the folder where the local git repository will be created or where it already exists.
string	branchName	Optionally specifies the branch to be checked out after the clone operation completes. This defaults to the GitHub remote repository's default branch (typically main or master).
string	username	Optionally specifies the GitHub username.
string	accessToken	Optionally specifies the GitHub Personal Access Token (PAT).
string	password	Optionally specifies the GitHub password.
string	email	Optionally specifies the GitHub email address for the current user.
string	userAgent	Optionally specifies the user-agent to be submitted with GitHub REST API calls. This defaults to "unknown".
IProfileClient	profileClient	Optionally specifies the IProfileClient instance to be used for retrieving secrets. You may also add your IProfileClient to ServiceContainer and the instance will use that if this parameter is null. Secrets will be queried only when a profile client is available.

Returns

Type	Description
Task<GitHubRepo>	The new GitHubRepo instance.

Remarks

note

At least one of accesstoken or password must be passed or be available via environment variables or the profile provider.

Exceptions

Type	Condition
LibGit2SharpException	Thrown when the local folder already exists.

ConnectAsync(string, string, string, string, string, string, IProfileClient)

Creates a GitHubRepo instance that's connected to GitHub account but is not associated with a local git repository. This is useful when you only need to perform GitHub operations.

Declaration

public static Task<GitHubRepo> ConnectAsync(string remoteRepoPath, string username = null, string accessToken = null, string password = null, string email = null, string userAgent = null, IProfileClient profileClient = null)

Parameters

Type	Name	Description
string	remoteRepoPath	Specifies the GitHub remote repository path, like: [SERVER/]OWNER/REPO
string	username	Optionally specifies the GitHub username.
string	accessToken	Optionally specifies the GitHub Personal Access Token (PAT).
string	password	Optionally specifies the GitHub password.
string	email	Optionally specifies the GitHub email address for the current user.
string	userAgent	Optionally specifies the user-agent to be submitted with GitHub REST API calls. This defaults to "unknown".
IProfileClient	profileClient	Optionally specifies the IProfileClient instance to be used for retrieving secrets. You may also add your IProfileClient to ServiceContainer and the instance will use that if this parameter is null. Secrets will be queried only when a profile client is available.

Returns

Type	Description
Task<GitHubRepo>	The new GitHubRepo instance.

Remarks

note

At least one of accesstoken or password must be passed or be available via environment variables or the profile provider.

note

NoLocalRepositoryException will be thrown whenever operations on the non-existent repository are attempted for GitHubRepo instance returned by this method.

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

Declaration

public void Dispose()

Dispose(bool)

Provides a way for subclasses to handle disposal of any additional objects or resources. Not that any overrides should be sure to call this base method.

Declaration

protected virtual void Dispose(bool disposing)

Parameters

Type	Name	Description
bool	disposing	Passed as true when disposing, false when finalizing.

~GitHubRepo()

Finalizer.

Declaration

protected ~GitHubRepo()

OpenAsync(string, string, string, string, string, string, IProfileClient)

Creates a GitHubRepo that references an existing local git repository as well as the associated GitHub remote repository API.

This requires GitHub credentials. These can be passed explicitly as parameters or can be retrieved automatically from the GITHUB_USERNAME, GITHUB_PASSWPORD, GITHUB_PAT and GITHUB_EMAIL environment variables or from the GITHUB[username], GITHUB[password], GITHUB[accesstoken] and GITHUB[email] secrets via an optional IProfileClient.

Declaration

public static Task<GitHubRepo> OpenAsync(string localRepoFolder, string username = null, string accessToken = null, string password = null, string email = null, string userAgent = null, IProfileClient profileClient = null)

Parameters

Type	Name	Description
string	localRepoFolder	Specifies the folder where the local git repository will be created or where it already exists.
string	username	Optionally specifies the GitHub username.
string	accessToken	Optionally specifies the GitHub Personal Access Token (PAT).
string	password	Optionally specifies the GitHub password.
string	email	Optionally specifies the GitHub email address for the current user.
string	userAgent	Optionally specifies the user-agent to be submitted with GitHub REST API calls. This defaults to "unknown".
IProfileClient	profileClient	Optionally specifies the IProfileClient instance to be used for retrieving secrets. You may also add your IProfileClient to ServiceContainer and the instance will use that if this parameter is null. Secrets will be queried only when a profile client is available.

Returns

Type	Description
Task<GitHubRepo>

Remarks

note

At least one of accesstoken or password must be passed or be available via environment variables or the profile provider.

Exceptions

Type	Condition
RepositoryNotFoundException	Thrown when the local repository doesn't exist.