Skip to main content

GitHub Package

The GitHub package offered by Modular Pipelines, in conjunction with the implemented OctoKit client library, facilitates a streamlined approach to interacting with remote GitHub repositories.

By leveraging this package, developers can more efficiently integrate their pipelines with GitHub, allowing for a smoother workflow and interaction with the platform's extensive API. The convenience afforded by this tool makes it an indispensable asset for anyone looking to automate tasks, synchronize data, or manage repositories programmatically on GitHub within their build pipelines.

Installation​

dotnet add package ModularPipelines.GitHub

GitHub Client​

Using Octokit in Modular Pipelines is pretty straightforward. Simply reference the ModularPipelines.GitHub package, and then, in your module, access the OctoKit client using GitHub().Client property as (an example):

public class GitHubModule : Module<string?>
{
    protected override async Task<string?> ExecuteAsync(
        IModuleContext context,
        CancellationToken cancellationToken)
    {
        var info = context.Tools.GitHub.RepositoryInfo;
        var user = await context.Tools.GitHub.Client.User.Get(info.Owner);

        context.Logger.LogInformation("User location: {Location}", user.Location);

        return user.Location;
    }
}

RepositoryInfo​

Various GitHub APIs need certain repository data to be passed to make them work. For general developer ergonomics and easy access, as an additional convenience to work with GitHub APIs, Modular Pipelines' GitHub() provides the RepositoryInfo property that holds various basic data for easy interaction with OctoKit.

This feature is really important because many services in the GitHub API need details such as the repository owner and the name of the repository. For example:

// Let's delete GitHub release with Id 12
var info = context.Tools.GitHub.RepositoryInfo;
var owner = info.Owner;
var repo = info.RepositoryName;

await context.Tools.GitHub.Client.Repository.Release.Delete(owner, repo, 12);

Client Auth​

Modular Pipelines' GitHub() automatically authenticates OctoKit client when:

  • Environment variable named GITHUB_TOKEN is set (which is automatically provided by GitHub when running the pipeline in the GitHub workflow)
  • By using property AccessToken inGitHubOptions record provided by the Modular Pipelines

Using GitHubOptions Record​

Configuring OctoKit auth using GitHubOptions is straightforward as it follows standard .NET practices for working with IConfiguration and IOptions<T>. When configuring your pipeline, use the usual practices for working with configuration to configure OctoKit auth:

var builder = Pipeline.CreateBuilder(args);

builder.Configuration
    .AddJsonFile("appsettings.json")
    .AddUserSecrets<Program>()
    .AddEnvironmentVariables();

// Registers a section from the configuration file with GitHubOptions
builder.Services.Configure<GitHubOptions>(builder.Configuration.GetSection("ModularPipelines:Secrets:GitHub"));

await builder.RunAsync();

where appsettings.json is constructed as follows:

{
  "ModularPipelines": {
    "Secrets": {
      "AccessToken": "your github access token"
    }
  }
}

Once configured, Modular Pipelines will handle authentication and authorization automatically by utilizing the provided access token and will deliver a GitHub client that is ready for immediate use.

Important Note: This is just an example; do not store any confidential data in appsettings.json, .env files, and similar. Use secret storage, key-vault services, etc., for storing sensitive data, and then use the described configuration practices as shown in the example above.

V4 migration​

Handwritten GitHub options, condition attributes, extension methods, and workflow models now use ModularPipelines.GitHub. Replace imports of .Attributes, .PipelineWriters, and the handwritten .Extensions/.Options types with the package root namespace. The generated gh CLI options and services retain their generated namespaces.

Use AddDistributedWorkflow(...) instead of WriteDistributedWorkflow(...) to register a workflow writer on the builder. SkipIfNoGitHubToken is now SkipIfNoGitHubTokenAttribute; attribute syntax [SkipIfNoGitHubToken] remains valid. The public RegisterGitHubContext method is hidden from IntelliSense and remains available for generated registration. Module code uses context.Tools.GitHub.

GitHub CLI option scope​

The GitHub CLI 2.98.0 root help exposes help/version actions, not shared command settings. GhOptions therefore has no executable-wide CLI options. The issue list manual labels --repo/-R as inherited from its command group; this does not make repository selection valid for gh auth status, gh config get, or gh api.

Set repository selection on the supported command record:

var options = new GhIssueListOptions { Repo = "owner/repository", Limit = 3 };
// gh issue list --limit=3 --repo=owner/repository

No global-option migration is required for this audit. Existing command-specific properties and command/version APIs remain unchanged. See the root CLI manual for the executable's controls.