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

Getting Started: SideRepoOps is ideal when you’re new to agentic workflows and want a low-risk way to experiment. You can test automation without adding files to your main repository or worrying about breaking existing workflows.

Key Benefits:

• Zero friction - No changes needed to your main repository
• Clean separation - AI-generated issues stay separate from organic development
• Private workflows - Store sensitive automation logic in a private repository
• Safe experimentation - Perfect for testing and learning before production deployment
• Centralized automation - Manage workflows for repositories you don’t directly control

Use SideRepoOps for workflow experimentation, creating a centralized automation hub, or managing automation for multiple repositories.

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/         │
└─────────────────┘          └──────────────────┘

In SideRepoOps, workflows run in GitHub Actions on the side repository but perform operations (create issues, PRs, comments) on the main repository using cross-repository authentication.

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 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 MAIN_REPO_PAT --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.MAIN_REPO_PAT }}
  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.MAIN_REPO_PAT }}
  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.MAIN_REPO_PAT }}  # Required for private repos
  create-issue:
    target-repo: "my-org/private-main-repo"

tools:
  github:
    mode: remote
    github-token: ${{ secrets.MAIN_REPO_PAT }}  # 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.MAIN_REPO_PAT }}
  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.MAIN_REPO_PAT }}
  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.MAIN_REPO_PAT }}
  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.MAIN_REPO_PAT }} 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.MAIN_REPO_PAT }}
    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.

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.MULTI_REPO_PAT }}
  create-issue:
    target-repo: ${{ inputs.target_repo }}  # Dynamic target
---

# Multi-Repository Automation

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

Using GitHub Apps

For enhanced security, use GitHub Apps instead of PATs. GitHub Apps provide automatic token expiration after job completion, more granular permission control, better audit trails, and can be installed at organization level.

See GitHub App for Safe Outputs 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.SIDE_REPO_PAT }}
  add-comment:
    target-repo: "my-org/automation-repo"

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

Related Patterns

• MultiRepoOps - Coordinate work across multiple repositories from main repo
• Orchestration - Orchestrate multi-issue initiatives
• IssueOps - Issue-driven automation patterns

Related Documentation

• Safe Outputs Reference - Complete safe output configuration
• GitHub Tools - GitHub API toolsets
• Authentication - Token types and precedence
• Security Best Practices - Authentication and security
• Reusing Workflows - Sharing workflows