Add GitHub Models integration

.github/copilot-instructions.md

@@ -55,7 +55,7 @@ When running tests in automated environments (including Copilot agent), **always
 
 ```bash
 # Correct - excludes quarantined tests (use this in automation)
-dotnet.sh test tests/Project.Tests/Project.Tests.csproj --filter-not-trait "quarantined=true"
+dotnet.sh test tests/Project.Tests/Project.Tests.csproj -- --filter-not-trait "quarantined=true"
 
 # For specific test filters, combine with quarantine exclusion
 dotnet.sh test tests/Project.Tests/Project.Tests.csproj -- --filter "TestName" --filter-not-trait "quarantined=true"

src/Aspire.Hosting.GitHub.Models/GitHubModelResource.cs

@@ -10,16 +10,16 @@ namespace Aspire.Hosting.GitHub.Models;
 /// </summary>
 public class GitHubModelResource : Resource, IResourceWithConnectionString, IResourceWithoutLifetime
 {
-    internal const string GitHubModelsEndpoint = "https://models.github.ai/inference";
-
     /// <summary>
     /// Initializes a new instance of the <see cref="GitHubModelResource"/> class.
     /// </summary>
     /// <param name="name">The name of the resource.</param>
     /// <param name="model">The model name.</param>
-    public GitHubModelResource(string name, string model) : base(name)
+    /// <param name="organization">The organization.</param>
+    public GitHubModelResource(string name, string model, ParameterResource? organization) : base(name)
     {
         Model = model;
+        Organization = organization;
     }
 
     /// <summary>
@@ -28,16 +28,27 @@ public GitHubModelResource(string name, string model) : base(name)
     public string Model { get; set; }
 
     /// <summary>
-    /// Gets or sets the API key for accessing GitHub Models.
+    /// Gets or sets the organization login associated with the organization to which the request is to be attributed.
+    /// </summary>
+    /// <remarks>
+    /// If set, the token must be attributed to an organization.
+    /// </remarks>
+    public ParameterResource? Organization { get; set; }
+
+    /// <summary>
+    /// Gets or sets the API key (PAT or GitHub App minted token) for accessing GitHub Models.
     /// </summary>
     /// <remarks>
     /// If not set, the value will be retrieved from the environment variable GITHUB_TOKEN.
+    /// The token must have the <code>models: read</code> permission if using a fine-grained PAT or GitHub App minted token.
     /// </remarks>
     public ParameterResource Key { get; set; } = new ParameterResource("github-api-key", p => Environment.GetEnvironmentVariable("GITHUB_TOKEN") ?? string.Empty, secret: true);
 
     /// <summary>
     /// Gets the connection string expression for the GitHub Models resource.
     /// </summary>
     public ReferenceExpression ConnectionStringExpression =>
-        ReferenceExpression.Create($"Endpoint={GitHubModelsEndpoint};Key={Key};Model={Model};DeploymentId={Model}");
+        Organization is not null
+            ? ReferenceExpression.Create($"Endpoint=https://models.github.ai/orgs/{Organization}/inference;Key={Key};Model={Model};DeploymentId={Model}")
+            : ReferenceExpression.Create($"Endpoint=https://models.github.ai/inference;Key={Key};Model={Model};DeploymentId={Model}");
 }

src/Aspire.Hosting.GitHub.Models/GitHubModelsExtensions.cs

@@ -3,6 +3,8 @@
 
 using Aspire.Hosting.ApplicationModel;
 using Aspire.Hosting.GitHub.Models;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Diagnostics.HealthChecks;
 
 namespace Aspire.Hosting;
 
@@ -17,16 +19,18 @@ public static class GitHubModelsExtensions
     /// <param name="builder">The <see cref="IDistributedApplicationBuilder"/>.</param>
     /// <param name="name">The name of the resource. This name will be used as the connection string name when referenced in a dependency.</param>
     /// <param name="model">The model name to use with GitHub Models.</param>
+    /// <param name="organization">The organization login associated with the organization to which the request is to be attributed.</param>
     /// <returns>A reference to the <see cref="IResourceBuilder{T}"/>.</returns>
-    public static IResourceBuilder<GitHubModelResource> AddGitHubModel(this IDistributedApplicationBuilder builder, [ResourceName] string name, string model)
+    public static IResourceBuilder<GitHubModelResource> AddGitHubModel(this IDistributedApplicationBuilder builder, [ResourceName] string name, string model, IResourceBuilder<ParameterResource>? organization = null)
     {
         ArgumentNullException.ThrowIfNull(builder);
         ArgumentException.ThrowIfNullOrEmpty(name);
         ArgumentException.ThrowIfNullOrEmpty(model);
 
-        var resource = new GitHubModelResource(name, model);
+        var resource = new GitHubModelResource(name, model, organization?.Resource);
 
         return builder.AddResource(resource)
+            .WithHealthCheck()
             .WithInitialState(new()
             {
                 ResourceType = "GitHubModel",
@@ -54,4 +58,47 @@ public static IResourceBuilder<GitHubModelResource> WithApiKey(this IResourceBui
 
         return builder;
     }
+
+    /// <summary>
+    /// Adds a health check to the GitHub Model resource.
+    /// </summary>
+    /// <param name="builder">The resource builder.</param>
+    /// <returns>The resource builder.</returns>
+    /// <remarks>
+    /// <para>
+    /// This method adds a health check that verifies the GitHub Models endpoint is accessible,
+    /// the API key is valid, and the specified model is available. The health check will:
+    /// </para>
+    /// <list type="bullet">
+    /// <item>Return <see cref="HealthStatus.Healthy"/> when the endpoint returns HTTP 200</item>
+    /// <item>Return <see cref="HealthStatus.Unhealthy"/> with details when the API key is invalid (HTTP 401)</item>
+    /// <item>Return <see cref="HealthStatus.Unhealthy"/> with error details when the model is unknown (HTTP 404)</item>
+    /// </list>
+    /// </remarks>
+    internal static IResourceBuilder<GitHubModelResource> WithHealthCheck(this IResourceBuilder<GitHubModelResource> builder)
+    {
+        ArgumentNullException.ThrowIfNull(builder);
+
+        var healthCheckKey = $"{builder.Resource.Name}_github_models_check";
+
+        // Register the health check
+        builder.ApplicationBuilder.Services.AddHealthChecks()
+            .Add(new HealthCheckRegistration(
+                healthCheckKey,
+                sp =>
+                {
+                    var httpClient = sp.GetRequiredService<IHttpClientFactory>().CreateClient("GitHubModelsHealthCheck");
+
+                    var resource = builder.Resource;
+
+                    return new GitHubModelsHealthCheck(httpClient, async () => await resource.ConnectionStringExpression.GetValueAsync(default).ConfigureAwait(false));
+                },
+                failureStatus: default,
+                tags: default,
+                timeout: default));
+
+        builder.WithHealthCheck(healthCheckKey);
+
+        return builder;
+    }
 }

src/Aspire.Hosting.GitHub.Models/GitHubModelsHealthCheck.cs

@@ -0,0 +1,118 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System.Data.Common;
+using System.Net;
+using System.Text.Json;
+using System.Text.Json.Serialization;
+using Microsoft.Extensions.Diagnostics.HealthChecks;
+
+namespace Aspire.Hosting.GitHub.Models;
+
+/// <summary>
+/// A health check for GitHub Models resources.
+/// </summary>
+/// <param name="httpClient">The HttpClient to use.</param>
+/// <param name="connectionString">The connection string.</param>
+internal sealed class GitHubModelsHealthCheck(HttpClient httpClient, Func<ValueTask<string?>> connectionString) : IHealthCheck
+{
+    /// <summary>
+    /// Checks the health of the GitHub Models endpoint by sending a test request.
+    /// </summary>
+    /// <param name="context">The health check context.</param>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <returns>A task that represents the asynchronous health check operation.</returns>
+    public async Task<HealthCheckResult> CheckHealthAsync(HealthCheckContext context, CancellationToken cancellationToken = default)
+    {
+        try
+        {
+            var builder = new DbConnectionStringBuilder() { ConnectionString = await connectionString().ConfigureAwait(false) };
+
+            using var request = new HttpRequestMessage(HttpMethod.Post, new Uri($"{builder["Endpoint"]}/chat/completions"));
+
+            // Add required headers
+            request.Headers.Add("Accept", "application/vnd.github+json");
+            request.Headers.Add("Authorization", $"Bearer {builder["Key"]?.ToString()}");
+            request.Headers.Add("X-GitHub-Api-Version", "2022-11-28");
+
+            // Create test payload with empty messages to minimize API usage
+            var payload = new
+            {
+                model = builder["Model"]?.ToString(),
+                messages = Array.Empty<object>()
+            };
+
+            var jsonPayload = JsonSerializer.Serialize(payload);
+            request.Content = new StringContent(jsonPayload, System.Text.Encoding.UTF8, "application/json");
+
+            using var response = await httpClient.SendAsync(request, cancellationToken).ConfigureAwait(false);
+
+            return response.StatusCode switch
+            {
+                HttpStatusCode.Unauthorized => HealthCheckResult.Unhealthy("GitHub Models API key is invalid or has insufficient permissions"),
+                HttpStatusCode.NotFound or HttpStatusCode.Forbidden or HttpStatusCode.BadRequest => await HandleErrorCode(response, cancellationToken).ConfigureAwait(false),
+                _ => HealthCheckResult.Unhealthy($"GitHub Models endpoint returned unexpected status code: {response.StatusCode}")
+            };
+        }
+        catch (Exception ex)
+        {
+            return HealthCheckResult.Unhealthy($"Failed to check GitHub Models endpoint: {ex.Message}", ex);
+        }
+    }
+
+    private static async Task<HealthCheckResult> HandleErrorCode(HttpResponseMessage response, CancellationToken cancellationToken)
+    {
+        GitHubErrorResponse? errorResponse = null;
+
+        try
+        {
+            var content = await response.Content.ReadAsStringAsync(cancellationToken).ConfigureAwait(false);
+            errorResponse = JsonSerializer.Deserialize<GitHubErrorResponse>(content);
+
+            if (errorResponse?.Error?.Code == "unknown_model")
+            {
+                var message = !string.IsNullOrEmpty(errorResponse.Error.Message)
+                    ? errorResponse.Error.Message
+                    : "Unknown model";
+                return HealthCheckResult.Unhealthy($"GitHub Models: {message}");
+            }
+            else if (errorResponse?.Error?.Code == "empty_array")
+            {
+                return HealthCheckResult.Healthy();
+            }
+            else if (errorResponse?.Error?.Code == "no_access")
+            {
+                return HealthCheckResult.Unhealthy($"GitHub Models: {errorResponse.Error.Message}");
+            }
+        }
+        catch
+        {
+        }
+
+        return HealthCheckResult.Unhealthy($"GitHub Models returned an unsupported resonse: ({response.StatusCode}) {errorResponse?.Error?.Message}");
+    }
+
+    /// <summary>
+    /// Represents the error response from GitHub Models API.
+    /// </summary>
+    private sealed class GitHubErrorResponse
+    {
+        [JsonPropertyName("error")]
+        public GitHubError? Error { get; set; }
+    }
+
+    /// <summary>
+    /// Represents an error from GitHub Models API.
+    /// </summary>
+    private sealed class GitHubError
+    {
+        [JsonPropertyName("code")]
+        public string? Code { get; set; }
+
+        [JsonPropertyName("message")]
+        public string? Message { get; set; }
+
+        [JsonPropertyName("details")]
+        public string? Details { get; set; }
+    }
+}

src/Aspire.Hosting.GitHub.Models/README.md

@@ -7,7 +7,7 @@ Provides extension methods and resource definitions for a .NET Aspire AppHost to
 ### Prerequisites
 
 - GitHub account with access to GitHub Models
-- GitHub [personal access token](https://docs.github.com/en/github-models/use-github-models/prototyping-with-ai-models#experimenting-with-ai-models-using-the-api) with appropriate permissions
+- GitHub [personal access token](https://docs.github.com/en/github-models/use-github-models/prototyping-with-ai-models#experimenting-with-ai-models-using-the-api) with appropriate permissions (`models: read`)
 
 ### Install the package