Add documentation for allowing Copilot to run workflows without approval

Co-authored-by: paulbkoch <46825734+paulbkoch@users.noreply.github.com>

Author: Copilot

.github/COPILOT_WORKFLOW_APPROVAL.md

@@ -0,0 +1,132 @@
+# Allowing Copilot to Run Workflows Without Manual Approval
+
+## Problem
+When GitHub Copilot creates a pull request or makes changes, workflows may require manual approval before running. This is a security feature implemented by GitHub to prevent unauthorized workflow execution.
+
+## Solution
+
+The ability to bypass workflow approval for Copilot is **primarily controlled by repository settings**, not the workflow file itself. However, there are several approaches you can take:
+
+### Option 1: Repository Settings (Recommended)
+
+This is the primary way to control workflow approvals for Copilot-created pull requests:
+
+1. **Navigate to Repository Settings**:
+   - Go to your repository on GitHub
+   - Click **Settings** > **Actions** > **General**
+
+2. **Configure Fork Pull Request Workflows**:
+   - Scroll down to **"Fork pull request workflows from contributors"**
+   - Choose one of the following options based on your security requirements:
+     - **"Require approval for first-time contributors who are new to GitHub"** (Recommended)
+       - This allows Copilot (and other established contributors) to run workflows automatically
+       - Only brand new GitHub users who have never contributed to the repository will need approval
+     - **"Don't require approval for any contributors"** (Least restrictive)
+       - All workflows run automatically, including from Copilot
+       - ⚠️ Use with caution as this reduces security
+
+3. **Click Save**
+
+### Option 2: Repository Rulesets (If Available)
+
+If your repository has rulesets configured, you may be able to add Copilot as a bypass actor:
+
+1. **Navigate to Settings > Rules > Rulesets**
+2. **Edit the relevant ruleset** that requires workflow approvals
+3. **Add the Copilot coding agent as a bypass actor** (if this option is available)
+4. **Save the ruleset**
+
+Note: This feature may not be available in all GitHub plans or may be a newer feature.
+
+### Option 3: Workflow File Modifications (Limited Effectiveness)
+
+While the workflow file itself cannot bypass GitHub's security requirement for bot approvals, you can make some modifications to optimize workflow execution:
+
+#### Use `pull_request_target` Event (Use with Caution)
+
+The `pull_request_target` event runs in the context of the base branch and always executes without approval. However, **this poses security risks** if not used carefully:
+
+```yaml
+on:
+  pull_request:  # Standard PR trigger (may require approval)
+  pull_request_target:  # Always runs (security risk if misused)
+```
+
+⚠️ **Security Warning**: `pull_request_target` gives the workflow access to repository secrets and runs with write permissions. Only use this for trusted operations that don't execute arbitrary code from the PR.
+
+#### Add Conditional Logic
+
+You can add conditions to skip certain jobs for Copilot if needed:
+
+```yaml
+jobs:
+  my_job:
+    if: github.actor != 'github-copilot[bot]' && github.actor != 'copilot-autofix[bot]'
+    runs-on: ubuntu-latest
+    steps:
+      # ... your steps
+```
+
+Or to run jobs ONLY for Copilot:
+
+```yaml
+jobs:
+  copilot_specific_job:
+    if: github.actor == 'github-copilot[bot]' || github.actor == 'copilot-autofix[bot]'
+    runs-on: ubuntu-latest
+    steps:
+      # ... your steps
+```
+
+## Current Workflow Analysis
+
+The current `interpret-CI` workflow uses the following triggers:
+
+```yaml
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+  schedule:
+```
+
+### Why Approval is Required
+
+- The `pull_request` trigger requires approval for pull requests from users who haven't contributed before (by default)
+- This includes bot accounts like Copilot
+- This is a GitHub security feature to prevent malicious actors from running arbitrary workflows
+
+### Recommended Action
+
+**The best solution is to adjust the repository settings** as described in Option 1 above. This is:
+- ✅ The officially supported method
+- ✅ More secure than modifying the workflow file
+- ✅ Easier to manage and audit
+- ✅ Doesn't require changes to the workflow YAML
+
+## Common Copilot Bot Usernames
+
+When working with conditions, these are common Copilot-related bot usernames:
+- `github-copilot[bot]`
+- `copilot-autofix[bot]`
+
+## Security Considerations
+
+When allowing workflows to run without approval, consider:
+
+1. **Code Review**: Ensure all code changes are reviewed before merging
+2. **Secrets Protection**: Workflows should not expose secrets or sensitive data
+3. **Resource Limits**: Workflows should have reasonable timeout and resource constraints
+4. **Branch Protection**: Use branch protection rules to prevent direct pushes to important branches
+
+## Further Reading
+
+- [GitHub Docs: Approving workflow runs from public forks](https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/approving-workflow-runs-from-public-forks)
+- [GitHub Docs: Managing GitHub Actions settings for a repository](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository)
+- [GitHub Docs: Events that trigger workflows](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows)
+
+## Conclusion
+
+**To allow Copilot to run workflows without approval, you need to change repository settings, not the workflow file.** The workflow file modifications described above provide limited additional control but do not bypass GitHub's core security requirements.
+
+Navigate to **Settings > Actions > General** and adjust the "Fork pull request workflows from contributors" setting to allow Copilot to run workflows automatically.