Proposal: Replace IssueOps Orchestration with Agentic Workflows from .github-private

[AlexDeMichieli]

Context

The current migration flow uses IssueOps -- submit-repos.yml scans for repos with GH_MIGRATION_TYPE custom properties, creates an issue on each target repo with the agent prompt as the issue body, and assigns Copilot. This works but has limitations:

• The issue body contains the entire agent prompt, which is fragile and hard to maintain
• Hooks and guardrails must be pushed to each target repo individually
• Developers see a confusing migration issue appear on their repo

Architecture: Before and After

Before (IssueOps)

+-------------------------------+
|  actions-migrations-via-       |
|  copilot (central repo)       |
|                                |
|  submit-repos.yml              |
|  - scans orgs for repos        |
|  - reads config.yaml           |
|  - for each repo:              |
|      - creates issue  <-- agent prompt pasted as issue body
|      - assigns Copilot         |
+---------------+----------------+
                | creates issues on target repos
                v
+-------------------------------+
|  target-repo-1                 |
|  - Jenkinsfile                 |
|  - issue #1 (migration) <-- full prompt in body, Copilot assigned
|  - .github/hooks/ ???  <-- hooks must be pushed per-repo
+-------------------------------+
|  target-repo-2                 |
|  - .gitlab-ci.yml              |
|  - issue #1 (migration)        |
|  - .github/hooks/ ???          |
+-------------------------------+
|  target-repo-N ...             |
+-------------------------------+

Problems:
- Agent prompt lives in issue body (fragile)
- Hooks need to be in each repo (doesn't scale)
- Developers see migration issues on their repos (confusing)
- Enterprise shared agents not fully utilized

After (Agentic Workflows from .github-private)

+-------------------------------+
|  .github-private         <-- org/enterprise level
|  (internal visibility)         |
|                                |
|  agents/                       |
|  - jenkins-migrator.agent.md   <-- enterprise shared agent
|  - gitlab-migrator.agent.md    |
|  - ...                         |
|                                |
|  knowledge/              <-- migration knowledge base
|  - migration-standards.md      |
|  - migration-guardrails.md     |
|  - actions-mapping/            |
|                                |
|  .github/                      |
|  - hooks/                <-- hooks enforced centrally
|  |   - hooks.json              |
|  |   - verify-ci-sources.sh    |
|  - workflows/                  |
|      - migrate.yml       <-- agentic workflow (replaces submit-repos.yml)
|          - selects agent       |
|          - targets repo        |
|          - invokes Copilot     |
+---------------+----------------+
                | agent runs on target repo with
                | enterprise agent + knowledge + hooks
                v
+-------------------------------+
|  target-repo-1                 |
|  - Jenkinsfile                 |
|  - (no setup needed)    <-- zero per-repo configuration
+-------------------------------+
|  target-repo-2                 |
|  - .gitlab-ci.yml              |
|  - (no setup needed)           |
+-------------------------------+
|  target-repo-N ...             |
+-------------------------------+

Result: PR opened on target repo with:
- .github/workflows/ci.yml (migrated workflow)
- .github/ci-archive/ (original files + audit log + scorecard)
- MIGRATION-README.md (validation results)

Proposal

Move the orchestration into .github-private using enterprise shared custom agents and agentic workflows.

How it works

1. Custom agents in .github-private/agents/ are automatically available across all repos in the org/enterprise
2. An agentic workflow in .github-private selects the right agent (based on GH_MIGRATION_TYPE) and invokes it against the target repo
3. The agent reads the knowledge base via MCP, migrates the CI files, and opens a PR on the target repo
4. Hooks enforce guardrails during the session

Key advantages over IssueOps

• No per-repo configuration -- agents, knowledge, and potentially hooks all live centrally in .github-private
• Cleaner developer experience -- no confusing migration issues created on target repos
• Easier maintenance -- update an agent or guardrail in one place, applies everywhere
• Simpler orchestration -- the workflow invokes the agent directly rather than creating issues as a proxy

Open questions

1. Do hooks in .github-private/.github/hooks/ apply when an enterprise shared agent runs on a target repo? This is the critical question -- if yes, hooks are solved. If not, we need copilot-setup-steps.yml as a fallback for the security guard hook.
2. How does the agentic workflow invoke the coding agent against a specific target repo? Need to confirm the API/CLI mechanism for programmatically starting a coding agent session with a specific custom agent on a remote repo.
3. What does the PR body look like? The migration output should be the body of the PR -- need to define the template.

Next steps

• Test hooks from .github-private on the EMU enterprise (volcano-coffee)
• Build a minimal proof-of-concept: one agentic workflow + jenkins-migrator agent + CI sources check hook
• Report findings back here

cc: @antgrutta @ssulei7

[antgrutta]

@AlexDeMichieli, we’ve created https://github.com/github/actions-migrations-via-copilot/issues/17 to capture the requirements for moving the batch processing to Agentic Workflows. I believe this addresses the concerns you raised here. As you continue experimenting, I’d encourage you to open a PR with a proposed implementation. Based on our conversations and the details you shared, we’re excited to see what you come up with. Please reach out if you need any support.

[AlexDeMichieli]

Closing in favor of #17

[AlexDeMichieli]

Closing this discussion — the proposal has been captured as issue #17 (implementation spec) and PR #21 (implementation with architectural review and hooks findings).

Key finding from testing: hooks do not propagate from .github-private to target repos. PR #21 adds a deploy-hooks.js bootstrap step to pre-deploy hooks to every target repo via the Contents API.

See also:

• Batch Mode: Failure Scenarios, Recovery, and Operational Gotchas #20 — Batch failure scenarios and recovery gotchas
• PR feat: Replace IssueOps with deterministic orchestrator + agentic workers #21 — Implementation with architectural decisions documented in the PR body