Use AI models from GitHub Models in your workflows.

Create a workflow to use the AI inference action:

name: 'AI inference'
on: workflow_dispatch

jobs:
  inference:
    permissions:
      models: read
    runs-on: ubuntu-latest
    steps:
      - name: Test Local Action
        id: inference
        uses: actions/ai-inference@v1
        with:
          prompt: 'Hello!'

      - name: Print Output
        id: output
        run: echo "${{ steps.inference.outputs.response }}"

You can also provide a prompt file instead of an inline prompt. The action supports both plain text files and structured .prompt.yml files:

steps:
  - name: Run AI Inference with Text File
    id: inference
    uses: actions/ai-inference@v1
    with:
      prompt-file: './path/to/prompt.txt'

For more advanced use cases, you can use structured .prompt.yml files that support templating, custom models, and JSON schema responses:

steps:
  - name: Run AI Inference with Prompt YAML
    id: inference
    uses: actions/ai-inference@v1
    with:
      prompt-file: './.github/prompts/sample.prompt.yml'
      input: |
        var1: hello
        var2: ${{ steps.some-step.outputs.output }}
        var3: |
          Lorem Ipsum
          Hello World
      file_input: |
        var4: ./path/to/long-text.txt
        var5: ./path/to/config.json

messages:
  - role: system
    content: Be as concise as possible
  - role: user
    content: 'Compare {{a}} and {{b}}, please'
model: openai/gpt-4o

messages:
  - role: system
    content: You are a helpful assistant that describes animals using JSON format
  - role: user
    content: |-
      Describe a {{animal}}
      Use JSON format as specified in the response schema
model: openai/gpt-4o
responseFormat: json_schema
jsonSchema: |-
  {
    "name": "describe_animal",
    "strict": true,
    "schema": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "The name of the animal"
        },
        "habitat": {
          "type": "string",
          "description": "The habitat the animal lives in"
        }
      },
      "additionalProperties": false,
      "required": [
        "name",
        "habitat"
      ]
    }
  }

Variables in prompt.yml files are templated using {{variable}} format and are supplied via the input parameter in YAML format. Additionally, you can provide file-based variables via file_input, where each key maps to a file path.

In addition to the regular prompt, you can provide a system prompt file instead of an inline system prompt:

steps:
  - name: Run AI Inference with System Prompt File
    id: inference
    uses: actions/ai-inference@v1
    with:
      prompt: 'Hello!'
      system-prompt-file: './path/to/system-prompt.txt'

This can be useful when model response exceeds actions output limit

steps:
  - name: Test Local Action
    id: inference
    uses: actions/ai-inference@v1
    with:
      prompt: 'Hello!'

  - name: Use Response File
    run: |
      echo "Response saved to: ${{ steps.inference.outputs.response-file }}"
      cat "${{ steps.inference.outputs.response-file }}"

This action supports integration with Model Context Protocol (MCP) servers, allowing the AI model to access external tools and services.

MCP servers are configured using a .github/.mcp.json file in your repository. This file defines which MCP servers to connect to and how to authenticate with them.

Basic Example (.github/.mcp.json):

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/directory"]
    },
    "github": {
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${GITHUB_TOKEN}",
        "X-MCP-Readonly": "true"
      }
    }
  }
}

Using Environment Variables:

The configuration supports environment variable substitution using ${VAR_NAME} or $VAR_NAME syntax. This is useful for keeping sensitive credentials out of your repository.

{
  "mcpServers": {
    "github": {
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${GITHUB_TOKEN}"
      }
    },
    "sentry": {
      "command": "npx",
      "args": ["-y", "@sentry/mcp-server@latest", "--host=github.sentry.io"],
      "env": {
        "SENTRY_ACCESS_TOKEN": "${SENTRY_TOKEN}",
        "SENTRY_HOST": "github.sentry.io"
      }
    }
  }
}

Workflow Example:

steps:
  - name: Checkout repository
    uses: actions/checkout@v4

  - name: AI Inference with MCP
    id: inference
    uses: actions/ai-inference@v1
    with:
      prompt: 'Analyze the repository and list any open issues'
      enable-mcp: true
    env:
      GITHUB_TOKEN: ${{ secrets.USER_PAT }}
      SENTRY_TOKEN: ${{ secrets.SENTRY_TOKEN }}

HTTP Servers - Connect to remote MCP servers via HTTP:

{
  "serverName": {
    "url": "https://api.example.com/mcp/",
    "headers": {
      "Authorization": "Bearer ${TOKEN}"
    }
  }
}

Stdio Servers - Run MCP servers as local processes:

{
  "serverName": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"],
    "env": {
      "DEBUG": "1"
    }
  }
}

You can restrict which tools are available from each MCP server by specifying a tools array in the server configuration. This is useful for:

• Limiting access to only necessary tools
• Improving security by restricting tool availability
• Reducing token usage by only including relevant tools in the inference context

Example with Tool Filtering:

{
  "mcpServers": {
    "github": {
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${GITHUB_TOKEN}"
      },
      "tools": ["search_issues", "issue_read", "search_code"]
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"],
      "tools": ["list_directory", "read_file"]
    }
  }
}

When you specify a tools array:

1. The action connects to the MCP server and retrieves all available tools
2. It filters the tools to only include those that are:
   • Listed in your tools configuration AND
   • Actually available from the server
3. Only the filtered tools are passed to the AI model for inference

If you omit the tools field, all available tools from the server will be used (default behavior).

By default, the action looks for .github/.mcp.json in your repository. You can specify a custom path:

steps:
  - name: AI Inference with Custom MCP Config
    uses: actions/ai-inference@v1
    with:
      prompt: 'Your prompt here'
      enable-mcp: true
      mcp-config-path: '.github/config/custom-mcp.json'

Various inputs are defined in action.yml to let you configure the action:

The AI inference action provides the following outputs:

In order to run inference with GitHub Models, the GitHub AI inference action requires models permissions.

permissions:
  contents: read
  models: read

This project includes a helper script, script/release designed to streamline the process of tagging and pushing new releases for GitHub Actions. For more information, see Versioning in the GitHub Actions toolkit.

GitHub Actions allows users to select a specific version of the action to use, based on release tags. This script simplifies this process by performing the following steps:

1. Retrieving the latest release tag: The script starts by fetching the most recent SemVer release tag of the current branch, by looking at the local data available in your repository.
2. Prompting for a new release tag: The user is then prompted to enter a new release tag. To assist with this, the script displays the tag retrieved in the previous step, and validates the format of the inputted tag (vX.X.X). The user is also reminded to update the version field in package.json.
3. Tagging the new release: The script then tags a new release and syncs the separate major tag (e.g. v1, v2) with the new release tag (e.g. v1.0.0, v2.1.2). When the user is creating a new major release, the script auto-detects this and creates a releases/v# branch for the previous major version.
4. Pushing changes to remote: Finally, the script pushes the necessary commits, tags and branches to the remote repository. From here, you will need to create a new release in GitHub so users can easily reference the new tags in their workflows.

This project is licensed under the terms of the MIT open source license. Please refer to MIT for the full terms.

Contributions are welcome! See the Contributor's Guide.