SideRepoOps

SideRepoOps is a development pattern where you run agentic workflows from a separate “side” repository that targets your main codebase. This keeps AI-generated issues, comments, and workflow runs isolated from your main repository, providing cleaner separation between automation infrastructure and your production code.

When to Use SideRepoOps

SideRepoOps is ideal when you’re new to agentic workflows and want a low-risk way to experiment — no changes needed to your main repository, AI-generated issues stay separate from organic development, and sensitive automation logic remains in a private repository. Use it for workflow experimentation, centralized automation across multiple repositories, or managing workflows for repositories you don’t directly control.

How It Differs from MultiRepoOps

While MultiRepoOps runs workflows from your main repository that create resources in other repositories, SideRepoOps inverts this pattern:

Pattern	Workflow Location	Target Repository	Use Case
MultiRepoOps	Main repository	Other repositories	Coordinate work across related projects
SideRepoOps	Separate side repo	Main repository	Isolate automation infrastructure from main codebase

Example Architecture:

┌─────────────────┐          ┌──────────────────┐
│  Side Repo      │          │  Main Repo       │
│  (workflows)    │ ────────>│  (target code)   │
│                 │   Uses   │                  │
│  - automation/  │   PAT    │  - src/          │
│  - .github/     │          │  - tests/        │
│    workflows/   │          │  - docs/         │
└─────────────────┘          └──────────────────┘

Tip

Testing with TrialOps Before deploying SideRepoOps workflows to production, use TrialOps to test them in isolated trial repositories. This lets you validate behavior and iterate on prompts without creating real issues in your repositories.

Setup Requirements

1. Create the Side Repository

Create a new repository (public or private) to host your agentic workflows. No code is required - just workflows.

gh repo create my-org/my-project-automation --private
gh repo clone my-org/my-project-automation
cd my-project-automation

2. Configure Personal Access Token (PAT)

Create a fine-grained PAT (this link pre-fills the token name, description, and permissions) with repository access to your main repository and grant these permissions: Contents (Read), Issues (Read+Write), Pull requests (Read+Write), and Metadata (Read).

For classic PATs, use the repo scope. Store the token as a secret:

gh aw secrets set GH_AW_MAIN_REPO_TOKEN --value "YOUR_PAT_HERE"

Tip

Security Best Practice Use fine-grained PATs scoped to specific repositories. Set expiration dates and rotate tokens regularly.

3. Enable GitHub Actions

Ensure GitHub Actions is enabled in your side repository settings.

Workflow Configuration

Basic SideRepoOps Workflow

Create a workflow in your side repository that targets the main repository:

---
on:
  workflow_dispatch:
    inputs:
      task_description:
        description: "What should the agent work on?"
        required: true

engine: copilot

permissions:
  contents: read

safe-outputs:
  github-token: ${{ secrets.GH_AW_MAIN_REPO_TOKEN }}
  create-issue:
    target-repo: "my-org/main-repo"
    title-prefix: "[automation] "
    labels: [automation, ai-generated]
  create-pull-request:
    target-repo: "my-org/main-repo"
    base-branch: main

tools:
  github:
    mode: remote
    toolsets: [repos, issues, pull_requests]
---

# Side Repository Automation

You are running from a separate automation repository and need to work on the main codebase.

**Target Repository**: my-org/main-repo

**Task**: {{inputs.task_description}}

**Instructions**:

1. Use GitHub tools to explore the main repository (search code, review issues/PRs, check documentation)
2. Complete the task by creating issues or PRs with clear descriptions and appropriate labels
3. All resources should include "[automation]" prefix, link to context, and have labels: automation, ai-generated

Remember: The workflow runs in the automation repo, but all outputs go to the main repo.

Scheduled Monitoring from Side Repo

Run scheduled checks on your main repository:

---
on: weekly on monday

engine: copilot

permissions:
  contents: read

safe-outputs:
  github-token: ${{ secrets.GH_AW_MAIN_REPO_TOKEN }}
  create-issue:
    target-repo: "my-org/main-repo"
    max: 5
    labels: [weekly-check, automation]

tools:
  github:
    mode: remote
    toolsets: [repos, issues, pull_requests, actions]
---

# Weekly Repository Health Check

Analyze the main repository and create issues for any concerns.

**Target Repository**: my-org/main-repo

Check for stale PRs (>30 days), failed CI runs on main, outdated dependencies with security advisories, documentation gaps, and high-complexity code needing refactoring.

Create issues for significant findings with clear problem descriptions, links to relevant code/PRs, suggested next steps, and priority labels.

GitHub Tools Configuration

When workflows run in a side repository, you must enable GitHub tools with mode: remote to access the main repository:

tools:
  github:
    mode: remote                    # Required for cross-repo access
    toolsets: [repos, issues, pull_requests]

Available toolsets: repos (files, code, commits, releases), issues (list/search/read), pull_requests (list/search/read), actions (workflow runs/artifacts), and context (repository metadata).

Note

GitHub tools with mode: local (Docker-based) can only access the repository where the workflow is running. Always use mode: remote for SideRepoOps.

Private Repository Access

For private repositories, your PAT must have explicit repository access with appropriate permission scopes (contents, issues, pull_requests):

safe-outputs:
  github-token: ${{ secrets.GH_AW_MAIN_REPO_TOKEN }}  # Required for private repos
  create-issue:
    target-repo: "my-org/private-main-repo"

tools:
  github:
    mode: remote
    github-token: ${{ secrets.GH_AW_MAIN_REPO_TOKEN }}  # Explicit token for tools
    toolsets: [repos, issues, pull_requests]

Caution

The default GITHUB_TOKEN provided by GitHub Actions cannot access other repositories. You must use a PAT with appropriate permissions for SideRepoOps.

Common Patterns

Triage from Side Repository

Run triage workflows on main repository issues:

---
on: every 6h

safe-outputs:
  github-token: ${{ secrets.GH_AW_MAIN_REPO_TOKEN }}
  add-labels:
    target-repo: "my-org/main-repo"
  add-comment:
    target-repo: "my-org/main-repo"

tools:
  github:
    mode: remote
    toolsets: [issues]
---

# Triage Main Repository Issues

Find unlabeled issues in my-org/main-repo and add appropriate labels.

Code Quality Monitoring

Monitor main repository for quality issues:

---
on: weekly on monday

safe-outputs:
  github-token: ${{ secrets.GH_AW_MAIN_REPO_TOKEN }}
  create-issue:
    target-repo: "my-org/main-repo"
    labels: [code-quality, automation]
    max: 10

tools:
  github:
    mode: remote
    toolsets: [repos, pull_requests]
---

# Weekly Code Quality Review

Analyze recent commits and PRs in my-org/main-repo for:
- Code complexity issues
- Missing test coverage
- Outdated dependencies
- Security vulnerabilities

Create issues for significant findings.

Documentation Sync

Keep documentation synchronized from side repository:

---
on:
  workflow_dispatch:
    inputs:
      docs_path:
        description: "Path to documentation folder"
        default: "docs/"

safe-outputs:
  github-token: ${{ secrets.GH_AW_MAIN_REPO_TOKEN }}
  create-pull-request:
    target-repo: "my-org/main-repo"
    base-branch: main
    title-prefix: "[docs] "

tools:
  github:
    mode: remote
    toolsets: [repos]
---

# Documentation Synchronization

Review documentation in {{inputs.docs_path}} of my-org/main-repo.
Create a PR with suggested improvements.

Troubleshooting

Authentication Failures

If you see “Resource not accessible by integration” errors, verify your PAT has access to the target repository, check permissions include required scopes, ensure the PAT hasn’t expired, and confirm github-token: ${{ secrets.GH_AW_MAIN_REPO_TOKEN }} is configured (not GITHUB_TOKEN).

GitHub Tools Not Working

If the agent cannot read files from the main repository, use mode: remote for GitHub tools and provide an explicit token if the main repo is private:

tools:
  github:
    mode: remote
    github-token: ${{ secrets.GH_AW_MAIN_REPO_TOKEN }}
    toolsets: [repos]

Issues Created in Wrong Repository

Always specify target-repo in safe outputs. Without it, safe outputs default to the repository where the workflow runs:

safe-outputs:
  create-issue:
    target-repo: "my-org/main-repo"

Unwanted Timeline Items

If automation creates unwanted cross-references in your main repository’s timelines (e.g., #123 references creating “mentioned in…” entries), use allowed-github-references to control reference escaping:

safe-outputs:
  allowed-github-references: []  # Escape all references
  create-issue:
    target-repo: "my-org/main-repo"

This prevents GitHub from auto-linking issue numbers and creating timeline entries. See Text Sanitization for details.

Slash Commands

GitHub Actions only delivers webhook events to workflows in the repository where the event occurred. Since SideRepoOps workflows live in a side repository, events from the main repository never reach them — slash_command: triggers cannot be used directly in a SideRepoOps workflow.

Recommended Bridge Pattern

The recommended approach is to keep a thin relay workflow in the main repository that listens for the slash command and forwards it to the side repository via workflow_dispatch. The side repository workflow does the actual work.

Step 1 — Relay workflow in the main repository:

---
on: /review

permissions:
  contents: read

safe-outputs:
  github-token: ${{ secrets.GH_AW_SIDE_REPO_TOKEN }}
  workflow-dispatch:
    target-repo: "my-org/automation-repo"
    workflow: "review.md"
    inputs:
      source_repo: "my-org/main-repo"
      pr_number: "${{ github.event.issue.number }}"
      comment_body: "${{ steps.sanitized.outputs.text }}"
---

# Review Relay

Forward this `/review` command to the automation repository for processing.

Step 2 — Review workflow in the side repository:

---
on:
  workflow_dispatch:
    inputs:
      source_repo:
        description: "Repository where the command was triggered"
        required: true
      pr_number:
        description: "Pull request number"
        required: true
      comment_body:
        description: "Sanitized comment text"
        required: true

engine: copilot

safe-outputs:
  github-token: ${{ secrets.GH_AW_MAIN_REPO_TOKEN }}
  add-comment:
    target-repo: "${{ inputs.source_repo }}"

tools:
  github:
    mode: remote
    toolsets: [repos, pull_requests]
---

# Code Review

Review pull request #{{inputs.pr_number}} in {{inputs.source_repo}}.

Context from the triggering comment: "{{inputs.comment_body}}"

Analyze the code changes and post a detailed review comment on the pull request.

Trade-offs

Approach	Isolation	Simplicity	Event Access
Slash command directly in main repo	Low — workflow lives in main repo	High — no relay needed	Full — all events available
Bridge pattern (relay + side repo)	High — AI logic stays in side repo	Medium — two workflows to maintain	Good — relay passes relevant context
Scheduled polling instead	High — no main repo changes needed	High — single workflow in side repo	Limited — no real-time response

Tip

If you only need a few slash commands, keep them in the main repository and use SideRepoOps only for scheduled and workflow_dispatch workflows. This gives you the best of both worlds with minimal complexity.

Advanced Topics

Multi-Target SideRepoOps

Manage multiple main repositories from one side repository:

---
on:
  workflow_dispatch:
    inputs:
      target_repo:
        description: "Target repository (owner/repo)"
        required: true
      task:
        description: "Task description"
        required: true

safe-outputs:
  github-token: ${{ secrets.GH_AW_MULTI_REPO_PAT }}
  create-issue:
    target-repo: ${{ inputs.target_repo }}  # Dynamic target
---

# Multi-Repository Automation

Work on user-specified repository: {{inputs.target_repo}}

Checking Out the Target Repository

When your workflow needs to run local tools against the target repository (for example, running tests, linters, or build scripts), check it out to a named path and explicitly navigate the agent into that directory:

---
on:
  workflow_dispatch:
    inputs:
      target_repo:
        description: "Target repository (owner/repo)"
        required: true

checkout:
  - repository: ${{ github.event.inputs.target_repo }}
    path: repo
    github-token: ${{ secrets.GH_AW_MAIN_REPO_TOKEN }}
    current: true

engine: copilot

permissions:
  contents: read

safe-outputs:
  github-token: ${{ secrets.GH_AW_MAIN_REPO_TOKEN }}
  create-pull-request:
    target-repo: ${{ inputs.target_repo }}
    base-branch: main
---

# Run Tests in Target Repository

Navigate into the folder where the target repository has been checked out into: cd ${{ github.workspace }}/repo

Run the test suite and report any failures.

Caution

current: true tells the agent which repository to treat as its primary target for GitHub operations — it does not automatically set the working directory. Without the explicit cd instruction in the prompt, the agent starts in $GITHUB_WORKSPACE (the side repository checkout) and must infer the correct directory on its own, which can lead to mistakes.

Using GitHub Apps

For enhanced security, use GitHub Apps instead of PATs.

See Using a GitHub App for Authentication for complete configuration including repository scoping options.

Bidirectional Sync

Create workflows in main repository that report back to side repository:

In main-repo:

on:
  issues:
    types: [opened, labeled]

safe-outputs:
  github-token: ${{ secrets.GH_AW_SIDE_REPO_TOKEN }}
  add-comment:
    target-repo: "my-org/automation-repo"

This creates a feedback loop where the side repository tracks automation effectiveness.

Related

Patterns: MultiRepoOps · ChatOps · Orchestration · IssueOps

Reference: Command Triggers · Cross-Repository Operations · Safe Outputs · GitHub Tools · Authentication · Reusing Workflows