Set up GitHub Models in the AppHost

This article is the reference for the Aspire GitHub Models hosting integration. It enumerates the AppHost APIs — with examples for both AppHost.cs and apphost.ts — that you use to model GitHub Model resources in your AppHost project.

If you’re new to the GitHub Models integration, start with the Get started with GitHub Models integrations guide. For how consuming apps read the connection information this page exposes, see Connect to GitHub Models.

Installation

To start building an Aspire app that uses GitHub Models, install the 📦 Aspire.Hosting.GitHub.Models NuGet package:

C#

Terminal

aspire add github-models

Learn more about aspire add in the command reference.

Or, choose a manual installation approach:

C# — AppHost.cs

#:package Aspire.Hosting.GitHub.Models@*

XML — AppHost.csproj

<PackageReference Include="Aspire.Hosting.GitHub.Models" Version="*" />

TypeScript

Terminal

aspire add github-models

Learn more about aspire add in the command reference.

This updates your aspire.config.json with the GitHub Models hosting integration package:

aspire.config.json

{
  "packages": {
    "Aspire.Hosting.GitHub.Models": "13.3.0"
  }
}

Add a GitHub Model resource

Once you’ve installed the hosting integration in your AppHost project, you can add a GitHub Model resource:

C#

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var chat = builder.AddGitHubModel("chat", GitHubModel.OpenAI.OpenAIGpt4oMini);

var exampleProject = builder.AddProject<Projects.ExampleProject>("apiservice")
    .WithReference(chat);

// After adding all resources, run the app...

TypeScript

TypeScript — apphost.ts

import { createBuilder, GitHubModelName } from './.modules/aspire.js';

const builder = await createBuilder();

const chat = await builder.addGitHubModel("chat", GitHubModelName.OpenAIGpt4oMini);

await builder.addNodeApp("api", "./api", "index.js")
    .withReference(chat);

// After adding all resources, run the app...

1. Calling AddGitHubModel (or addGitHubModel) creates a GitHubModelResource. It registers a secret parameter for the API key that defaults to the GITHUB_TOKEN environment variable.

2. The model identifier selects which GitHub-hosted model to target. In C#, use the strongly-typed GitHubModel constants grouped by publisher; in TypeScript, use the GitHubModelName enum.

3. The AppHost reference call configures a connection in the consuming project named after the resource (for example, chat in the preceding example).

Note

When you reference a GitHub Model resource from the AppHost, Aspire makes several properties available to the consuming project, such as the endpoint URI, API key, and model name. For a complete list of these properties and per-language connection examples, see Connect to GitHub Models.

Use a model identifier string

If you prefer to specify the model by its raw string identifier rather than a constant, use AddGitHubModel (C#) with the string overload or addGitHubModelById (TypeScript):

C#

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var chat = builder.AddGitHubModel("chat", "openai/gpt-4o-mini");

var exampleProject = builder.AddProject<Projects.ExampleProject>("apiservice")
    .WithReference(chat);

// After adding all resources, run the app...

TypeScript

TypeScript — apphost.ts

import { createBuilder } from './.modules/aspire.js';

const builder = await createBuilder();

const chat = await builder.addGitHubModelById("chat", "openai/gpt-4o-mini");

await builder.addNodeApp("api", "./api", "index.js")
    .withReference(chat);

// After adding all resources, run the app...

Tip

In C#, use the strongly-typed GitHubModel constants to avoid typos — they’re grouped by publisher (for example, GitHubModel.OpenAI.OpenAIGpt4oMini, GitHubModel.Microsoft.Phi4MiniInstruct, GitHubModel.DeepSeek.DeepSeekV30324). In TypeScript, use the GitHubModelName enum (for example, GitHubModelName.OpenAIGpt4oMini, GitHubModelName.DeepSeekV30324).

Use default API key parameter

Calling AddGitHubModel("chat", ...) (or addGitHubModel("chat", ...)) automatically creates a secret parameter named chat-gh-apikey. Aspire resolves its value in this order:

1. The Parameters:chat-gh-apikey configuration key (user secrets, appsettings.*, or environment variables).
2. The GITHUB_TOKEN environment variable.

If neither source provides a value, startup throws an exception. In Codespaces and GitHub Actions, GITHUB_TOKEN is populated automatically. For local development, provide a fine-grained personal access token with models: read scope via user secrets:

Terminal

aspire secret set Parameters:chat-gh-apikey github_pat_YOUR_TOKEN_HERE

Use a custom API key parameter

Replace the default parameter by creating your own secret parameter and passing it to WithApiKey (or withApiKey):

C#

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var apiKey = builder.AddParameter("my-gh-token", secret: true);

var chat = builder.AddGitHubModel("chat", GitHubModel.OpenAI.OpenAIGpt4oMini)
                  .WithApiKey(apiKey);

var exampleProject = builder.AddProject<Projects.ExampleProject>("apiservice")
    .WithReference(chat);

// After adding all resources, run the app...

TypeScript

TypeScript — apphost.ts

import { createBuilder, GitHubModelName } from './.modules/aspire.js';

const builder = await createBuilder();

const apiKey = await builder.addParameter("my-gh-token", { secret: true });

const chat = await builder.addGitHubModel("chat", GitHubModelName.OpenAIGpt4oMini);
await chat.withApiKey(apiKey);

await builder.addNodeApp("api", "./api", "index.js")
    .withReference(chat);

// After adding all resources, run the app...

Note

Parameters marked secret: true are stored in the user secrets store and never appear in plain text in logs or the dashboard.

Specify an organization

For organization-attributed requests, pass an organization parameter:

C#

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var organization = builder.AddParameter("github-org");

var chat = builder.AddGitHubModel("chat", GitHubModel.OpenAI.OpenAIGpt4oMini, organization);

var exampleProject = builder.AddProject<Projects.ExampleProject>("apiservice")
    .WithReference(chat);

// After adding all resources, run the app...

TypeScript

TypeScript — apphost.ts

import { createBuilder, GitHubModelName } from './.modules/aspire.js';

const builder = await createBuilder();

const organization = await builder.addParameter("github-org");

const chat = await builder.addGitHubModel("chat", GitHubModelName.OpenAIGpt4oMini, {
    organization,
});

await builder.addNodeApp("api", "./api", "index.js")
    .withReference(chat);

// After adding all resources, run the app...

When an organization is specified, the endpoint changes to https://models.github.ai/orgs/{organization}/inference and the token must be attributed to that organization in GitHub.

Add a health check

Add an optional health check to verify endpoint reachability and API key validity:

C#

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var chat = builder.AddGitHubModel("chat", GitHubModel.OpenAI.OpenAIGpt4oMini)
                  .WithHealthCheck();

var exampleProject = builder.AddProject<Projects.ExampleProject>("apiservice")
    .WithReference(chat);

// After adding all resources, run the app...

TypeScript

TypeScript — apphost.ts

import { createBuilder, GitHubModelName } from './.modules/aspire.js';

const builder = await createBuilder();

const chat = await builder.addGitHubModel("chat", GitHubModelName.OpenAIGpt4oMini);
await chat.withHealthCheck();

await builder.addNodeApp("api", "./api", "index.js")
    .withReference(chat);

// After adding all resources, run the app...

Caution

Because health checks count against GitHub Models rate limits, use this sparingly — for example when debugging connectivity issues. The health check executes only once per application instance to minimize API usage.

Available models

GitHub Models supports a broad and growing catalog of models. Use the strongly-typed constants for the most accurate list:

Publisher	C# constant (examples)	TypeScript enum (examples)
OpenAI	GitHubModel.OpenAI.OpenAIGpt4oMini	GitHubModelName.OpenAIGpt4oMini
OpenAI	GitHubModel.OpenAI.OpenAIGpt41Mini	GitHubModelName.OpenAIGpt41Mini
DeepSeek	GitHubModel.DeepSeek.DeepSeekV30324	GitHubModelName.DeepSeekV30324
DeepSeek	GitHubModel.DeepSeek.DeepSeekR1	GitHubModelName.DeepSeekR1
Microsoft	GitHubModel.Microsoft.Phi4MiniInstruct	GitHubModelName.Phi4MiniInstruct (see note)
Meta	GitHubModel.Meta.MetaLlama318BInstruct	GitHubModelName.MetaLlama318BInstruct

Note

In TypeScript, the GitHubModelName enum is a single flat list and does not use publisher-grouped sub-namespaces. This is a known gap compared to the C# API. Check the enum values in .modules/aspire.ts for the complete list.

For the full catalogue, visit the GitHub Models Marketplace.

Connection properties

For the full reference of GitHub Models connection properties — and how consuming apps in C#, TypeScript, Python, and Go read them — see Connect to GitHub Models.

See also

• Get started with the GitHub Models integrations
• Connect to GitHub Models
• GitHub Models Marketplace
• GitHub Models documentation