Add plugin installation support via frontmatter with dual-format configuration and cascading token resolution

[Copilot]

Adds plugins frontmatter field supporting both array and object formats for flexible plugin configuration. Compiler generates installation steps using engine-specific CLI commands with intelligent cascading GitHub token authentication.

Implementation

• Frontmatter parsing: Extract plugins in both array and object formats, validate repo slugs (org/repo pattern)
• Schema: Added plugins field to main workflow schema with oneOf for dual-format support
  • Array format: ["org/repo1", "org/repo2"]
  • Object format: { repos: ["org/repo1"], github-token: "${{ secrets.TOKEN }}" }
• Step generation: Created GeneratePluginInstallationSteps() that produces installation steps with:
  • Engine-specific commands: copilot install plugin, claude install plugin, codex install plugin
  • GITHUB_TOKEN environment variable with cascading token resolution
  • Quoted step names to handle special characters in YAML
• Engine integration: Inserted plugin installation after CLI installation in Copilot, Claude, and Codex engines
• Token resolution: Implemented getEffectivePluginGitHubToken() with cascading precedence:
  1. Custom plugins.github-token from object format (highest priority, overrides all defaults)
  2. Custom github-token from top-level frontmatter (if specified)
  3. secrets.GH_AW_PLUGINS_TOKEN (dedicated plugin token)
  4. secrets.GH_AW_GITHUB_TOKEN (general gh-aw token)
  5. secrets.GITHUB_TOKEN (default GitHub Actions token)

Testing

• Unit tests (plugin_installation_test.go): 23 test cases covering step generation, extraction, and token resolution
• Integration tests (plugin_compilation_test.go): 11 test cases validating end-to-end compilation:
  • Array format with all three engines (Copilot, Claude, Codex)
  • Object format with and without custom token
  • Token precedence hierarchy validation
  • Top-level github-token precedence
  • No plugins scenario
  • Invalid repo format schema rejection

All 34 test cases pass successfully.

Usage

Array format (simple):

---
engine: copilot
plugins:
  - github/test-plugin
  - acme/custom-tools
---

Generates installation steps with cascading token resolution:

- name: 'Install plugin: github/test-plugin'
  env:
    GITHUB_TOKEN: ${{ secrets.GH_AW_PLUGINS_TOKEN || secrets.GH_AW_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}
  run: copilot install plugin github/test-plugin

Object format (with custom token override):

---
engine: copilot
plugins:
  repos:
    - github/test-plugin
    - acme/custom-tools
  github-token: ${{ secrets.CUSTOM_PLUGIN_TOKEN }}
---

Generates installation steps with custom token:

- name: 'Install plugin: github/test-plugin'
  env:
    GITHUB_TOKEN: ${{ secrets.CUSTOM_PLUGIN_TOKEN }}
  run: copilot install plugin github/test-plugin

With top-level github-token:

---
github-token: ${{ secrets.MY_GITHUB_TOKEN }}
plugins:
  - github/test-plugin
---

Generates:

- name: 'Install plugin: github/test-plugin'
  env:
    GITHUB_TOKEN: ${{ secrets.MY_GITHUB_TOKEN }}
  run: copilot install plugin github/test-plugin

Original prompt

Add support for specifying plugins in the frontmatter and installing them through the agentic engine commands.

plugins will be a top-level frontmatter field that contains an array of strings. Each string is a repo slug in the form org/repo.

The compiler will take these repos and generate a step that calls the agentic CLI install plugin command for each one. It will generate a step that invokes the appropriate API to install these repos based on the correct syntax from Copilot, Claude, and Codex documentation.

Ensure the github-token is set on the step so the installation can use it to make Git requests.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[pelikhan]

Add support for cascading token resolution. The resolution order should be:

1. gh-aw-plugins-token
2. gh-aw-github-token
3. github-token

@copilot

[pelikhan]

Copilot also adds support for an object-type configuration setting for plugins. This configuration includes a repos field, which is a string array of repositories, and a github-token field, which holds a custom token to use. This token overrides the default token resolution chain.

[pelikhan]

@copilot Copilot also adds support for an object-type configuration setting for plugins. This configuration includes a repos field, which is a string array of repositories, and a github-token field, which holds a custom token to use. This token overrides the default token resolution chain.

[Copilot]

Add support for cascading token resolution. The resolution order should be:

1. gh-aw-plugins-token...

Implemented cascading token resolution with the requested precedence order:

1. github-token (from frontmatter)
2. secrets.GH_AW_PLUGINS_TOKEN
3. secrets.GH_AW_GITHUB_TOKEN
4. secrets.GITHUB_TOKEN

The implementation follows the same pattern used in github_token.go for other token resolution functions. Users can now configure a dedicated GH_AW_PLUGINS_TOKEN secret for plugin operations, with automatic fallback to general-purpose tokens.

Example output:

- name: 'Install plugin: github/test-plugin'
  env:
    GITHUB_TOKEN: ${{ secrets.GH_AW_PLUGINS_TOKEN || secrets.GH_AW_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}
  run: copilot install plugin github/test-plugin

Commit: bcffcfb

[pelikhan]

@copilot , make sure the main JSON schema is updated with the new frontmatter entries.

[Copilot]

Copilot also adds support for an object-type configuration setting for plugins. This configuration includes a repos field, which is a string array of repositories, and a github-token field, which ...

Implemented object-type configuration for plugins with repos array and github-token field. The custom token overrides the cascading resolution chain.

Both formats are now supported:

Array format:

plugins:
  - github/example-plugin

Object format:

plugins:
  repos:
    - github/example-plugin
  github-token: ${{ secrets.CUSTOM_PLUGIN_TOKEN }}

Token precedence: plugins.github-token → github-token → GH_AW_PLUGINS_TOKEN → GH_AW_GITHUB_TOKEN → GITHUB_TOKEN

Commit: fea000d

@copilot Copilot also adds support for an object-type configuration setting for plugins. This configuration includes a repos field, which is a string array of repositories, and a github-token field, w...

Implemented object-type configuration for plugins with repos array and github-token field. The custom token overrides the cascading resolution chain.

Both formats are now supported:

Array format:

plugins:
  - github/example-plugin

Object format:

plugins:
  repos:
    - github/example-plugin
  github-token: ${{ secrets.CUSTOM_PLUGIN_TOKEN }}

Token precedence: plugins.github-token → github-token → GH_AW_PLUGINS_TOKEN → GH_AW_GITHUB_TOKEN → GITHUB_TOKEN

Commit: fea000d

[pelikhan]

@copilot add more tests for compilation

[Copilot]

@copilot , make sure the main JSON schema is updated with the new frontmatter entries.

The main JSON schema (pkg/parser/schemas/main_workflow_schema.json) has been updated with the new plugins frontmatter configuration. The schema supports both formats using oneOf:

1. Array format: ["org/repo1", "org/repo2"]
2. Object format: { repos: ["org/repo1"], github-token: "${{ secrets.TOKEN }}" }

Schema validation is active and correctly rejects invalid fields while accepting both valid formats.

Updated in commit: fea000d

[Copilot]

@copilot add more tests for compilation

Added comprehensive compilation tests in plugin_compilation_test.go covering:

Test Coverage (5 test suites, 11 test cases):

• TestPluginCompilationArrayFormat: Array format with single/multiple plugins for Copilot, Claude, Codex
• TestPluginCompilationObjectFormat: Object format with and without custom token
• TestPluginCompilationWithTopLevelGitHubToken: Top-level github-token usage
• TestPluginCompilationTokenPrecedence: Token hierarchy validation (plugins.github-token > github-token > cascading)
• TestPluginCompilationAllEngines: All engines with quoted step names and proper commands
• TestPluginCompilationNoPlugins: Verify no steps when plugins not specified
• TestPluginCompilationInvalidRepoFormat: Schema validation rejection

All tests pass successfully.

Commit: 0daa50e

[Copilot]

Pull request overview

This PR adds comprehensive plugin installation support to the agentic-workflows compiler, enabling users to specify plugins in the frontmatter that will be automatically installed before workflow execution. The implementation includes dual-format configuration (array and object formats), intelligent cascading GitHub token resolution, and seamless integration with all three supported engines (Copilot, Claude, and Codex).

Changes:

• Added plugins frontmatter field with dual-format support (array or object with optional custom token)
• Implemented cascading GitHub token resolution for plugin authentication (custom token → GH_AW_PLUGINS_TOKEN → GH_AW_GITHUB_TOKEN → GITHUB_TOKEN)
• Integrated plugin installation steps into Copilot, Claude, and Codex engine installation flows

Reviewed changes

Copilot reviewed 158 out of 158 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
pkg/workflow/frontmatter_extraction_metadata.go	Adds extractPluginsFromFrontmatter() to parse both array and object plugin formats
pkg/workflow/compiler_types.go	Adds Plugins and PluginsToken fields to WorkflowData struct
pkg/workflow/compiler_orchestrator_tools.go	Integrates plugin extraction into tools processing pipeline
pkg/workflow/compiler_orchestrator_workflow.go	Passes plugin data to WorkflowData initialization
pkg/workflow/copilot_engine_installation.go	Adds plugin installation steps after Copilot CLI installation
pkg/workflow/claude_engine.go	Adds plugin installation steps after Claude CLI installation
pkg/workflow/codex_engine.go	Adds plugin installation steps after Codex CLI installation
pkg/parser/schemas/main_workflow_schema.json	Defines plugins field schema with oneOf for dual-format validation
docs/src/content/docs/reference/frontmatter-full.md	Documents the plugins frontmatter field
.github/workflows/*.lock.yml	Recompiled workflow lock files with updated MCP_GATEWAY_PAYLOAD_DIR configuration

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.