Getting started with the GitHub Copilot SDK installation and project setup in C# can feel overwhelming if you're new to AI-powered development tools. I've walked through this process many times, and I can tell you that once you understand the steps for GitHub Copilot SDK installation and project setup in C#, it's straightforward. This guide will take you through every step of the process, from installing the CLI tools to verifying your first working application. Whether you're building a console app or an ASP.NET Core web service, you'll have everything you need to start integrating AI capabilities into your .NET applications by the end of this article.
Prerequisites Checklist
Before we dive into the GitHub Copilot SDK setup C# process, let's make sure you have everything you need to succeed. The installation process requires a few components to be in place, and missing any of these will cause problems down the line. I've seen developers waste hours troubleshooting only to realize they were missing a basic prerequisite, so let's verify everything upfront.
Here's what you need before starting:
- .NET 8 SDK or later installed on your machine (verify with
dotnet --version) - GitHub account with an active GitHub Copilot subscription (Individual, Business, or Enterprise)
- GitHub CLI (gh) installed and available in your PATH
- Terminal or command prompt with admin/elevated privileges (for installing CLI extensions)
- Internet connection for downloading packages and authenticating
If you're interested in learning more about AI coding tools in general, I have a practical guide that covers the broader landscape.
Step 1: Install the GitHub Copilot CLI
The GitHub Copilot CLI is the foundation that powers the SDK. Unlike the IDE extension you might be familiar with, the CLI provides a programmatic interface that the SDK uses to communicate with GitHub's AI models. Without this component properly installed and authenticated, the SDK won't be able to function.
Note: CLI commands and configuration options are based on the SDK's current preview state. Check the official repository for up-to-date setup instructions.
First, you need to install the GitHub CLIif you haven't already. Download it from the official GitHub CLI website, or use a package manager like winget on Windows, brew on macOS, or apt on Linux. Once you have the base GitHub CLI installed, add the Copilot extension:
gh extension install github/gh-copilot
This command downloads and installs the Copilot CLI extension. The process usually takes just a few seconds. After installation completes, verify that everything is working correctly by checking the version:
gh copilot --version
You should see output showing the installed version number. If you get an error about the command not being found, double-check that your GitHub CLI installation is in your system PATH.
Next, authenticate with GitHub. The Copilot CLI needs permission to access your GitHub account and verify your Copilot subscription:
gh auth login
Follow the interactive prompts to complete authentication. You'll typically choose to authenticate via your web browser, which opens a page where you can authorize the GitHub CLI. Make sure you're logged into the GitHub account that has the Copilot subscription. After authentication succeeds, the CLI stores your credentials securely for future use.
Step 2: GitHub Copilot SDK Installation and Project Setup in C# -- Install the NuGet Package
With the CLI installed and authenticated, you're ready to add the GitHub Copilot SDK to your .NET projects. The SDK is distributed as a NuGet package, making it easy to integrate into any .NET application. The package handles all the complexity of communicating with the Copilot CLI and provides a clean, idiomatic C# API for working with AI models.
To install the GitHub Copilot SDK NuGet package in an existing project, navigate to your project directory and run:
dotnet add package GitHub.Copilot.SDK
As of February 2026, the current stable version is v0.1.25. The package is being actively developed, so expect regular updates with new features and improvements. The SDK has minimal dependencies and integrates cleanly with modern .NET applications.
You can optionally also install the Microsoft.Extensions.AI package, which provides additional abstractions and integration with dependency injection patterns I've covered before:
dotnet add package Microsoft.Extensions.AI
After running these commands, open your .csproj file to verify the package references were added correctly. You should see entries like this:
<ItemGroup>
<PackageReference Include="GitHub.Copilot.SDK" Version="0.1.25" />
</ItemGroup>
If you prefer to specify the version explicitly during installation, you can use:
dotnet add package GitHub.Copilot.SDK --version 0.1.25
Step 3: Create a New .NET Project
If you're starting from scratch rather than adding the SDK to an existing project, you'll want to create a new .NET console application. Console apps are perfect for learning and testing the SDK because they have minimal overhead and let you focus on the AI integration without worrying about web frameworks or UI concerns.
Create a new console application with:
dotnet new console -n CopilotSdkDemo
cd CopilotSdkDemo
This creates a basic .NET console application targeting .NET 8 by default (assuming you have .NET 8 SDK installed). The project will have a simple Program.cs file with a "Hello, World!" template.
For projects that will use the GitHub Copilot SDK, I recommend organizing your code with a clear structure from the beginning. Here's a recommended layout:
- Program.cs -- Main entry point and CopilotClient initialization
- Services/ -- Custom service classes that use the SDK
- Models/ -- Request/response models and data structures
- Configuration/ -- Options classes for SDK configuration
Even for a simple console app, having this structure makes it easier to expand your application later. Once your project is created, add the NuGet packages as described in Step 2.
Step 4: Verify the Setup with Hello World
Now comes the exciting part -- writing your first working program with the GitHub Copilot SDK. This verification step ensures that all the pieces are working together correctly. I always recommend starting with a simple test program before building more complex features, because it helps isolate any configuration issues early.
Replace the contents of your Program.cs file with this verification program:
// Hello world verification program
using GitHub.Copilot.SDK;
Console.WriteLine("Starting GitHub Copilot SDK verification...");
try
{
await using var client = new CopilotClient();
await client.StartAsync();
Console.WriteLine("✓ CopilotClient connected successfully");
await using var session = await client.CreateSessionAsync(new SessionConfig
{
Model = "gpt-4.1" // Fast model for verification
});
Console.WriteLine("✓ CopilotSession created successfully");
var tcs = new TaskCompletionSource<string>();
var response = new System.Text.StringBuilder();
session.On(evt =>
{
switch (evt)
{
case AssistantMessageEvent msg: response.Append(msg.Data.Content); break;
case SessionIdleEvent: tcs.TrySetResult(response.ToString()); break;
case SessionErrorEvent err: tcs.TrySetException(new Exception(err.Data.Message)); break;
}
});
await session.SendAsync(new MessageOptions { Prompt = "Say 'Setup complete!' in exactly those words." });
var result = await tcs.Task.WaitAsync(TimeSpan.FromSeconds(30));
Console.WriteLine($"✓ AI Response: {result}");
Console.WriteLine("
Setup verification PASSED -- GitHub Copilot SDK is working correctly!");
}
catch (Exception ex)
{
Console.WriteLine($"✗ Setup verification FAILED: {ex.Message}");
Console.WriteLine("Check that GitHub Copilot CLI is installed and authenticated.");
}
Run the program with:
dotnet run
If everything is configured correctly, you should see output similar to this:
Starting GitHub Copilot SDK verification...
✓ CopilotClient connected successfully
✓ CopilotSession created successfully
✓ AI Response: Setup complete!
Setup verification PASSED -- GitHub Copilot SDK is working correctly!
This program tests the complete workflow: creating a client, establishing a session, sending a prompt, and receiving a response. If you see the success message, congratulations -- your GitHub Copilot SDK setup C# environment is fully functional!
If you encounter errors, they'll typically fall into one of the categories I cover in the Troubleshooting section below.
Setting Up for ASP.NET Core
While console applications are great for testing and learning, many real-world scenarios involve web APIs and services. Setting up the GitHub Copilot SDK in an ASP.NET Core application requires a slightly different approach because you'll want to use dependency injection and proper service lifetime management. If you're interested in modern ASP.NET Core patterns, check out my article on ASP.NET Core with Needlr.
Create a new ASP.NET Core Web API project:
dotnet new webapi -n CopilotSdkWebApi
cd CopilotSdkWebApi
dotnet add package GitHub.Copilot.SDK
The key difference in ASP.NET Core applications is that you want to register the CopilotClient as a singleton service and ensure it starts when your application starts. Here's the recommended setup in your Program.cs:
// ASP.NET Core registration
using GitHub.Copilot.SDK;
var builder = WebApplication.CreateBuilder(args);
// Register CopilotClient as singleton
builder.Services.AddSingleton<CopilotClient>(sp =>
new CopilotClient(new CopilotClientOptions
{
// Use default path (searches PATH) or specify explicitly:
// CliPath = "/usr/local/bin/gh"
}));
// Start the client during app startup
builder.Services.AddHostedService<CopilotClientStartupService>();
var app = builder.Build();
app.MapGet("/health", () => "GitHub Copilot SDK is running");
await app.RunAsync();
public class CopilotClientStartupService(CopilotClient client) : IHostedService
{
public Task StartAsync(CancellationToken _) => client.StartAsync();
public Task StopAsync(CancellationToken _) => client.DisposeAsync().AsTask();
}
This pattern ensures that the CopilotClient is created once, started automatically when your application starts, and properly disposed when the application shuts down. The hosted service pattern is the recommended approach for managing background resources in ASP.NET Core applications.
You can then inject the CopilotClient into your controllers, minimal API handlers, or other services just like any other dependency. This makes testing easier and keeps your code clean and maintainable.
Environment and Configuration
The GitHub Copilot SDK provides several configuration options through the CopilotClientOptions class. Understanding these options helps you customize the SDK's behavior to match your environment and requirements. I've found that most developers can stick with the defaults, but there are situations where custom configuration is necessary.
The most commonly used configuration options include:
CLI Path: By default, the SDK searches your system PATH for the GitHub CLI (gh command). If your GitHub CLI is installed in a non-standard location, or if you have multiple versions installed, you can specify the exact path:
var client = new CopilotClient(new CopilotClientOptions
{
CliPath = "/usr/local/bin/gh" // Linux/Mac example
// or on Windows: CliPath = "C:\Program Files\GitHub CLI\gh.exe"
});
Port Configuration: The SDK communicates with the Copilot CLI over a local network port. In most cases, the SDK automatically selects an available port (subject to change in future versions), but you can specify one explicitly if needed for firewall rules or network policies:
var client = new CopilotClient(new CopilotClientOptions
{
Port = 8080 // Specify exact port
});
Timeout Settings: You can configure various timeout values for operations. This is particularly useful in production environments where you need predictable behavior:
var client = new CopilotClient(new CopilotClientOptions
{
StartupTimeout = TimeSpan.FromSeconds(30),
RequestTimeout = TimeSpan.FromMinutes(2)
});
For a more comprehensive look at configuration options and advanced patterns, see my complete guide to the GitHub Copilot SDK.
Troubleshooting Common Issues
Even with careful setup, you might encounter issues during installation or first run. I've seen these problems repeatedly in my work with developers learning the SDK, and they almost always fall into a few common categories. Here's what to watch for and how to fix the most frequent problems.
Copilot CLI Not Found in PATH: If you get an error saying the gh command or gh-copilot extension can't be found, the issue is typically that the GitHub CLI isn't in your system PATH. On Windows, you may need to restart your terminal or IDE after installing the CLI. On Linux or Mac, check that the installation added the CLI to your PATH by running which gh. If it's not found, you'll need to add it manually or reinstall using a package manager.
Authentication Expired or Invalid: The error message "not authenticated" or "invalid credentials" means your GitHub CLI authentication has expired or wasn't completed successfully. Run gh auth login again to re-authenticate. Make sure you're using the same GitHub account that has the Copilot subscription. You can verify your current authentication status with gh auth status.
Firewall or Network Restrictions: The SDK communicates with the Copilot CLI over local network ports. If you're in a corporate environment with strict firewall rules, you might need to whitelist these local connections. The SDK uses localhost (127.0.0.1) communication only, but some enterprise security software blocks this by default. Work with your IT department if you suspect firewall issues.
"Copilot Not Licensed" Error: This error means your GitHub account doesn't have an active Copilot subscription, or the CLI can't verify it. Double-check that your subscription is active in your GitHub settings. If you have both a personal and work GitHub account, make sure the CLI is authenticated with the correct one. Enterprise users should verify that their organization has enabled Copilot for their account.
Model Not Available: If you get an error about a specific model not being available (like "gpt-4o" or "claude-sonnet-4"), it might be that your subscription tier doesn't include that model, or the model name has changed. Try using "gpt-4.1" as shown in the examples -- it's widely available and works well for most use cases.
Keeping the SDK Up to Date
The GitHub Copilot SDK is under active development, with new features, improvements, and bug fixes released regularly. Staying current with the latest version ensures you have access to the newest capabilities and any security patches. I make it a habit to check for updates monthly, and I recommend you do the same.
To update the SDK to the latest version in your project:
dotnet add package GitHub.Copilot.SDK
This command updates to the latest stable release. If you want to check what versions are available before updating, you can search NuGet:
dotnet package search GitHub.Copilot.SDK
Or visit the NuGet package page directly to see version history and release notes.
For preview features and cutting-edge capabilities, the SDK team sometimes releases preview versions. You can opt into these with:
dotnet add package GitHub.Copilot.SDK --version 0.2.0-preview.1
However, I recommend sticking with stable releases for production applications. Preview versions are great for testing upcoming features but may have breaking changes or undocumented behavior.
Don't forget to also keep the GitHub Copilot CLI extension updated:
gh extension upgrade gh-copilot
Keeping both the SDK and CLI in sync helps avoid compatibility issues. The SDK documentation usually specifies the minimum required CLI version for each release.
FAQ
Developers often have questions when setting up the GitHub Copilot SDK installation and project setup in C# for the first time. Here are answers to the most common questions I encounter when helping teams get started with their GitHub Copilot SDK installation and project setup in C# environments.
Does the GitHub Copilot SDK work on Linux and Mac?
Yes, the SDK is fully cross-platform and works identically on Windows, Linux, and macOS. The only requirement is that you have .NET 8 or later installed and the GitHub CLI available for your platform. I regularly develop with the SDK on both Windows and Ubuntu, and I haven't encountered any platform-specific issues. The CLI paths and installation commands will vary slightly by platform, but the SDK code itself is platform-agnostic.
What if I'm behind a corporate firewall or proxy?
The GitHub Copilot SDK communicates with the CLI over localhost connections, which usually aren't affected by proxy settings. However, the CLI itself needs internet access to reach GitHub's servers. If you're behind a corporate proxy, configure the GitHub CLI with your proxy settings using gh config set http_proxy <proxy-url>. Some organizations have policies that restrict AI tools -- check with your IT department before installing. For more details on getting started with the SDK in enterprise environments, see my getting started guide.
Do I need a GitHub Copilot Individual subscription or does Enterprise work too?
Both individual and enterprise subscriptions work with the SDK. GitHub Copilot Business and Enterprise tiers actually provide the same API access as individual subscriptions, so you won't be limited in functionality. The main differences are in billing, administration, and policy controls -- not in what the SDK can do. If you're using an enterprise subscription, make sure your organization administrator has enabled Copilot for your account.
Can I use the SDK without installing the GitHub CLI?
No, the GitHub CLI with the Copilot extension is a required component. The SDK doesn't communicate directly with GitHub's API -- instead, it acts as a client for the locally-running Copilot CLI. This architecture provides better security, handles authentication automatically, and gives you the same AI models and capabilities across all interfaces (IDE, CLI, and SDK). Think of the CLI as the engine and the SDK as the steering wheel -- you need both for the system to work.
Conclusion
You've now completed the full GitHub Copilot SDK setup C# process, from installing the CLI tools through verifying your first working application. We covered console applications, ASP.NET Core integration, configuration options, and troubleshooting common issues. With this foundation in place, you're ready to start building AI-powered features into your .NET applications.
The GitHub Copilot SDK opens up exciting possibilities for integrating AI capabilities directly into your code. Whether you're building chatbots, code assistants, content generators, or intelligent automation tools, the SDK provides a clean and powerful interface for working with state-of-the-art language models. Start with simple experiments, gradually add complexity, and don't hesitate to explore the official documentation and samples.
Remember that the SDK is evolving rapidly, so check back regularly for updates and new features. The patterns and practices you've learned in this guide will serve as a solid foundation as you build more sophisticated applications. Happy coding, and enjoy exploring what's possible with AI-powered .NET development!