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

Use SideRepoOps to reduce noise by keeping AI-generated issues separate from organic development, store sensitive workflows in a private repository, or manage automation for repositories you don’t directly control. It’s ideal for workflow experimentation and creating a centralized automation hub.

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.

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"

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:
  schedule:
    - cron: "0 9 * * 1"  # Weekly Monday 9am UTC

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).

Caution

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]

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

Managing Generated Issues

Issue Transfer Workflow

Review automation-generated issues with gh issue list --label automation, transfer valuable ones to project boards or milestones, update labels as needed, and close false positives:

# Add to project and milestone
gh issue edit 123 --add-project "Main Project Board" --milestone "v2.0"

# Update labels
gh issue edit 123 --remove-label automation --add-label feature

# Close false positives
gh issue close 124 --reason "not planned"

Issue Organization Strategy

Use labels to distinguish between automation stages:

Label	Purpose
automation	Initially applied to all AI-generated issues
needs-review	Awaiting human review
approved	Human-validated and ready for work
false-positive	Not applicable; will be closed
transferred	Moved to proper project/milestone

---
safe-outputs:
  create-issue:
    target-repo: "my-org/main-repo"
    labels: [automation, needs-review]  # Start with review stage
---

All created issues should start with automation + needs-review labels.

Common Patterns

Triage from Side Repository

Run triage workflows on main repository issues:

---
on:
  schedule:
    - cron: "0 */6 * * *"  # Every 6 hours

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:
  schedule:
    - cron: "0 2 * * 1"  # Weekly Monday 2am UTC

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.

Best Practices

Security: Rotate PATs quarterly with expiration dates, minimize token scope to required permissions, use GitHub Apps for automatic token revocation, audit workflow runs regularly, and restrict who can trigger workflows.

Workflow Design: Mark AI-generated items with distinctive labels and [automation] prefixes, set appropriate rate limits with max: values, handle permission failures gracefully, and document cross-repo relationships.

Issue Management: Schedule regular reviews of automation-generated issues, document the review → approve → transfer process, track false positive rates, deduplicate before creating issues, and preserve context by linking to triggering events.

Repository Organization:

side-repo/
├── .github/
│   └── workflows/
│       ├── triage-main.md           # Scheduled triage
│       ├── quality-check.md         # Code quality monitoring
│       ├── doc-sync.md              # Documentation sync
│       └── manual-task.md           # Manual dispatch tasks
├── docs/
│   ├── README.md                    # Side repo documentation
│   └── workflow-guide.md            # How to use workflows
└── .env.example                     # Required secrets documentation

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"

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:

safe-outputs:
  app:
    app-id: ${{ vars.AUTOMATION_APP_ID }}
    private-key: ${{ secrets.AUTOMATION_APP_KEY }}
    owner: "my-org"
    repositories: ["main-repo"]
  create-issue:
    target-repo: "my-org/main-repo"

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.

Example Use Cases

Experimentation Repository: Test agentic workflows without affecting main development. Side repo creates issues with experiment label in main repo, reviewed weekly to promote successful experiments.

Third-Party Repository Monitoring: Monitor open-source dependencies for security issues using scheduled workflows that create internal tracking issues in your private side repo.

Cross-Organization Automation: Consulting teams can manage multiple client repositories using parameterized workflows with PATs that have access to client repositories.

Related Patterns

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

Related Documentation

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