Implement agent and repository imports with runtime .github folder merging

[Copilot]

Agent files and entire repositories can be imported from external repositories using the owner/repo/path@ref or owner/repo@ref formats. When imported, the entire .github folder from the remote repository is automatically merged at runtime.

Two Import Modes

1. Repository Import (owner/repo@ref) - NEW

Imports entire .github folder without agent extraction:

imports:
  - github/github-deep-research-agent@main  # Merges .github folder only

Use case: Import supporting files, tools, workflows from a repository without using an agent.

2. Agent File Import (owner/repo/.github/agents/agent.md@ref)

Imports specific agent file and merges .github folder:

imports:
  - acme-org/ai-agents/.github/agents/code-reviewer.md@v1.0.0

Use case: Use a specific agent with all its supporting files.

Changes

Documentation (4 new/updated files)

• New example guide (docs/src/content/docs/examples/agent-imports.md) - Complete walkthrough with practical examples, versioning strategies, and best practices
• Imports reference (docs/src/content/docs/reference/imports.md) - Agent files section covering local vs remote imports, caching behavior
• Custom agents reference (docs/src/content/docs/reference/custom-agents.md) - Remote import examples and versioning
• Packaging guide (docs/src/content/docs/guides/packaging-imports.md) - Agent import section with team collaboration patterns

Runtime .github Folder Merging (7 code files)

When an agent or repository is imported from a remote repository, the compiler automatically adds a merge step that:

• Uses sparse checkout to efficiently download only the .github folder from the remote repository
• Copies files one by one from the remote .github to the current repository's .github folder
• Fails on file conflicts to prevent silent overwrites
• Cleans up temporary directories after merging
• Supports multiple repository imports in a single workflow

Implementation:

• actions/setup/js/merge_remote_agent_github_folder.cjs - JavaScript script that performs the sparse checkout and merge
• pkg/parser/import_processor.go - Track repository imports and agent import specs
• pkg/parser/remote_fetch.go - Detect repository-only imports (owner/repo@ref)
• pkg/workflow/compiler_types.go - Add RepositoryImports and AgentImportSpec fields
• pkg/workflow/compiler_orchestrator_workflow.go - Pass import data through compilation
• pkg/workflow/compiler_yaml_main_job.go - Generate merge step after checkout in workflows
• .github/workflows/scout.md - Updated to import github/github-deep-research-agent@main

Usage Examples

Repository Import (NEW)

Import entire .github folder without using an agent:

---
on: issues
engine: copilot
imports:
  - github/github-deep-research-agent@main  # Repository import - merges .github folder
permissions:
  contents: read
  issues: write
---

# Research with Deep Research Agent Tools

Agent Import

Import specific agent file and merge .github folder:

---
on: pull_request
engine: copilot
imports:
  - acme-org/ai-agents/.github/agents/code-reviewer.md@v1.0.0
permissions:
  contents: read
  pull-requests: write
---

# Automated Code Review

Multiple Repository Imports

---
imports:
  - org1/research-agents@v1.0.0  # Repository import
  - org2/tools@main               # Another repository import
  - shared/common.md              # Local file import
---

How It Works

Repository Import (owner/repo@ref):

1. Compile time: Detected as 2-part import, added to RepositoryImports list
2. Runtime: Merge step uses sparse checkout to download .github/ folder and merges it into workspace
3. No agent extraction: Files are just made available, no agent is used

Agent Import (owner/repo/.github/agents/agent.md@ref):

1. Compile time: Agent content extracted, import spec tracked
2. Runtime: Merge step downloads .github/ folder and merges it
3. Agent used: Extracted agent content is passed to AI engine

Both modes:

• Use Git sparse checkout (efficient)
• Fail on file conflicts (prevents silent overwrites)
• Clean up temporary directories
• Support multiple imports per workflow

Detection Logic

The system automatically detects import type:

• Repository import: Exactly 2 path segments (owner/repo), no file extension
• File import: 1 segment (local file) or 3+ segments (remote file path)
• Exclusions: Paths starting with shared/, .github/, ., or / are treated as local

Scout Workflow Update

Scout now imports the deep research agent repository:

imports:
  - github/github-deep-research-agent@main  # NEW - repository import
  - shared/reporting.md                     # Local file import
  - shared/mcp/tavily.md                    # Local file import
  # ... other local imports

Generated merge step:

- name: Merge remote .github folder
  env:
    GH_AW_REPOSITORY_IMPORTS: '["github/github-deep-research-agent@main"]'
  with:
    script: |
      const { setupGlobals } = require('/opt/gh-aw/actions/setup_globals.cjs');
      setupGlobals(core, github, context, exec, io);
      const { main } = require('/opt/gh-aw/actions/merge_remote_agent_github_folder.cjs');
      await main();

Organizations can maintain agent libraries with supporting files:

acme-org/ai-agents/
└── .github/
    ├── agents/
    │   ├── code-reviewer.md
    │   ├── security-auditor.md
    │   └── performance-analyst.md
    └── workflows/          # Supporting files also available at runtime
        └── shared/

Documentation

Agent Imports Example:

Imports Reference:

Custom Agents Reference:

Remote agents are cached in .github/aw/imports/ by commit SHA for offline compilation. Only one agent file (local or remote) can be imported per workflow.

Test Results

✅ All parser tests pass
✅ TestCJSFilesNoActionsRequires passes
✅ TestLockFilesHaveNoBundledRequires passes
✅ Scout workflow compiles successfully (78.3 KB)
✅ Build and format successful

[!WARNING]

Custom agent used: technical-doc-writer
AI technical documentation writer for GitHub Actions library using GitHub Docs voice

Custom agent used: technical-doc-writer
AI technical documentation writer for GitHub Actions library using GitHub Docs voice

Original prompt

Ability to import agents from repos

https://github.com/github/github-deep-research-agent

Custom agent used: technical-doc-writer
AI technical documentation writer for GitHub Actions library using GitHub Docs voice

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[pelikhan]

@copilot the compiler must add a step so that the contents of the imported repo .github folder need to be merge in the current .github. If there is any file clash, fail. This must happen at runtime in the action. Use sparse checkout to a temp foldeer, copy file by file.
Create a JavaScript script for this.

[Copilot]

@copilot the compiler must add a step so that the contents of the imported repo .github folder need to be merge in the current .github. If there is any file clash, fail. This must happen at runtime in...

Implemented runtime .github folder merging for remote agent imports in commit a086fd3.

The solution:

• Created merge_remote_agent_github_folder.cjs script that uses sparse checkout to efficiently download only the .github folder from the remote agent repository
• Copies files one by one to the current repository's .github folder
• Fails the workflow if any file conflicts are detected (no silent overwrites)
• Runs automatically after checkout when an agent is imported from a remote repository

The merge step is added to the workflow with environment variables:

• GH_AW_AGENT_FILE: Path to the agent file (e.g., .github/agents/my-agent.md)
• GH_AW_AGENT_IMPORT_SPEC: Original import specification (e.g., owner/repo/.github/agents/agent.md@v1.0.0)

Example generated workflow step:

- name: Merge remote agent .github folder
  uses: actions/github-script@...
  env:
    GH_AW_AGENT_FILE: ".github/agents/code-reviewer.md"
    GH_AW_AGENT_IMPORT_SPEC: "acme-org/ai-agents/.github/agents/code-reviewer.md@v1.0.0"
  with:
    script: |
      const script = require('./actions/setup/js/merge_remote_agent_github_folder.cjs');
      return script.main();

[pelikhan]

@copilot update scout to import the github deep research agent and invoke it the prompt.

[pelikhan]

@copilot we want to be able to import the repo url. In that case, we import the entire .github folder only (shallow) but do not extract the agent.

[Copilot]

@copilot update scout to import the github deep research agent and invoke it the prompt.

The github/github-deep-research-agent repository appears to be private or not yet available. I found several public alternatives:

• tarun7r/deep-research-agent - Multi-agent research system with LangGraph
• SalesforceAIResearch/enterprise-deep-research - Enterprise deep research
• Cerno-AI/Cerno-Agentic-Local-Deep-Research - Local-first research tool

Could you clarify:

1. Should I use one of these public alternatives?
2. Or is there a specific agent file path in the github/github-deep-research-agent repo I should reference (if it's an internal GitHub repo)?
3. Or should I create a placeholder/example showing how scout would import such an agent once it's available?

The scout workflow is already set up for deep research with Tavily, arXiv, DeepWiki, and Microsoft Docs MCPs. With the agent import feature we just implemented, we can add an agent import once we know the correct repository and path.

[Copilot]

@copilot we want to be able to import the repo url. In that case, we import the entire .github folder only (shallow) but do not extract the agent.

Implemented repository-only imports in commit a1f86ad.

Now you can import entire repositories using just owner/repo@ref format:

imports:
  - github/github-deep-research-agent@main  # Merges .github folder, no agent extraction

The system automatically:

• Detects 2-part imports (owner/repo@ref) as repository imports
• Uses sparse checkout to download only the .github folder
• Merges all files without extracting/using an agent
• Fails on file conflicts
• Supports multiple repository imports in a single workflow

This is separate from agent file imports (owner/repo/.github/agents/agent.md@ref) which do extract and use the agent.