Merge #148: docs: [#147] Document GitHub Copilot agent firewall configuration

d790707 docs: [#147] create copilot agent firewall documentation (copilot-swe-agent[bot])
5e1e8f8 Initial plan (copilot-swe-agent[bot])

Pull request description:

  Phase 1 (repository settings) was completed by admin: `opentofu.org` added to custom allowlist to unblock OpenTofu installer. This PR completes Phase 2 (documentation) and Phase 3 (verification).

  ## Changes

  ### Created `docs/contributing/copilot-agent-firewall.md`
  Comprehensive reference for firewall configuration:
  - Current configuration: custom domain (`opentofu.org`) and recommended allowlist status
  - Admin instructions: step-by-step configuration walkthrough
  - Domain vs URL rules: when to use each allowlist type
  - Security: best practices, limitations, minimal whitelist approach
  - Maintenance: adding domains, troubleshooting DNS/connection errors
  - History: configuration change tracking table

  ### Updated cross-references
  - `docs/contributing/README.md`: Added firewall doc to quick reference table
  - `packages/dependency-installer/README.md`: Added "GitHub Copilot Agent Requirements" section linking to firewall configuration

  ## Context

  Without `opentofu.org` in allowlist:
  ```bash
  $ cargo run --bin dependency-installer install --dependency opentofu
  ERROR: curl: (6) Could not resolve host: get.opentofu.org
  ```

  With configuration complete, OpenTofu installer can download from `get.opentofu.org` and install successfully. Other dependencies (Ansible, cargo-machete, LXD) covered by recommended allowlist.

  Closes #147

  <!-- START COPILOT CODING AGENT SUFFIX -->

  <details>

  <summary>Original prompt</summary>

  >
  > ----
  >
  > *This section details on the original issue you should resolve*
  >
  > <issue_title>Configure Copilot Agent Firewall for Dependency Installer</issue_title>
  > <issue_description>## Overview
  >
  > Configure GitHub Copilot agent's firewall to allow network access to domains required by the dependency installer binaries. The Copilot agent environment has a restricted firewall that blocks access to external domains by default.
  >
  > ## Problem Statement
  >
  > When GitHub Copilot agent attempts to install dependencies using the `dependency-installer` binary, network requests are blocked by the agent's firewall:
  >
  > ```bash
  > $ cargo run -p torrust-dependency-installer --bin dependency-installer -- install --dependency opentofu
  > 2025-11-05T19:46:23.668278Z ERROR torrust_dependency_installer::app: Command failed error=Install command failed: Failed to install specific dependency: Installation failed: Failed to install dependency 'opentofu': Failed to download installer: curl: (6) Could not resolve host: get.opentofu.org
  > ```
  >
  > This prevents the agent from installing OpenTofu and running pre-commit checks.
  >
  > ## Required Configuration
  >
  > **Domain to Whitelist**: `opentofu.org`
  >
  > - Allows traffic to `opentofu.org` and all subdomains (e.g., `get.opentofu.org`)
  > - Required for OpenTofu installer script and package downloads
  >
  > **Already Covered by Recommended Allowlist**:
  > - Ubuntu/Debian package repositories (for Ansible)
  > - Rust package registry/crates.io (for cargo-machete)
  > - Snap store (for LXD)
  >
  > ## Implementation Steps
  >
  > ### Phase 1: Repository Settings Configuration (15-30 min)
  >
  > **Prerequisites**: Repository admin access required
  >
  > 1. Navigate to: `Settings` → `Copilot` → `coding agent`
  > 2. Verify **Enable firewall** is ON
  > 3. Verify **Recommended allowlist** is ON
  > 4. Click **Custom allowlist**
  > 5. Add domain: `opentofu.org`
  > 6. Click **Add Rule** → **Save changes**
  >
  > ### Phase 2: Documentation (15-30 min)
  >
  > - Create `docs/contributing/copilot-agent-firewall.md`
  > - Document configured domains and rationale
  > - Document configuration steps
  > - Update related documentation
  >
  > ### Phase 3: Verification (15-30 min)
  >
  > - Test OpenTofu installation in Copilot agent
  > - Verify no firewall warnings appear
  > - Update documentation if needed
  >
  > **Total Estimate**: 45 minutes - 1.5 hours
  >
  > ## Acceptance Criteria
  >
  > **Configuration**:
  > - [ ] `opentofu.org` added to custom allowlist
  > - [ ] Recommended allowlist remains enabled
  > - [ ] Firewall remains enabled
  >
  > **Documentation**:
  > - [ ] New doc: `docs/contributing/copilot-agent-firewall.md`
  > - [ ] Includes all configured domains with rationale
  > - [ ] Includes step-by-step instructions
  > - [ ] Links to GitHub documentation
  >
  > **Verification**:
  > - [ ] Copilot agent can install OpenTofu successfully
  > - [ ] No firewall warnings for configured domains
  > - [ ] Pre-commit checks pass
  >
  > ## Related Documentation
  >
  > - [GitHub Docs: Customizing the agent firewall](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/customize-the-agent-firewall)
  > - [Dependency Installer Package](https://github.com/torrust/torrust-tracker-deployer/blob/main/packages/dependency-installer/README.md)
  >
  > ## Notes
  >
  > ⚠️ **Requires Manual Implementation**: This issue cannot be implemented by Copilot agent because it requires repository admin access to modify settings. Must be done manually by a repository administrator.
  >
  > **Security**: Keep firewall and recommended allowlist enabled. Only add specific required domains (minimal whitelist approach).
  >
  > ## Specification
  >
  > Full specification: [docs/issues/configure-copilot-agent-firewall-for-dependency-installer.md](https://github.com/torrust/torrust-tracker-deployer/blob/main/docs/issues/configure-copilot-agent-firewall-for-dependency-installer.md)</issue_description>
  >
  > ## Comments on the Issue (you are @copilot in this section)
  >
  > <comments>
  > <comment_new><author>@josecelano</author><body>
  > ## ✅ Phase 1 Complete: Repository Settings Configured
  >
  > The Copilot agent firewall has been configured with the required domain:
  >
  > **Custom Allowlist Configuration**:
  > - ✅ Added domain: `opentofu.org`
  >   - This allows traffic to `opentofu.org` and all subdomains (e.g., `get.opentofu.org`)
  > - ✅ Firewall remains enabled
  > - ✅ Recommended allowlist remains enabled
  >
  > **Next Steps**:
  > - [ ] Phase 2: Create documentation (`docs/contributing/copilot-agent-firewall.md`)
  > - [ ] Phase 3: Verify OpenTofu installation works in Copilot agent environment
  >
  > **Configuration completed by**: Repository administrator
  > **Date**: November 5, 2025</body></comment_new>
  > </comments>
  >

  </details>

  - Fixes #147

  <!-- START COPILOT CODING AGENT TIPS -->
  ---

  💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more [Copilot coding agent tips](https://gh.io/copilot-coding-agent-tips) in the docs.

ACKs for top commit:
  josecelano:
    ACK d790707

Tree-SHA512: cba583af5b206e147c6245474dadb084214444731b58ad9c615cc06e10fe1cb7443118fa5713cfecce5718584bed4172cb57d378ac961c0466981f55cb4fbcf4

Author: josecelano

docs/contributing/README.md

@@ -20,6 +20,7 @@ This guide will help you understand our development practices and contribution w
 | Known issues and expected behaviors  | [known-issues.md](./known-issues.md)                         |
 | Logging best practices               | [logging-guide.md](./logging-guide.md)                       |
 | GitHub Markdown pitfalls             | [github-markdown-pitfalls.md](./github-markdown-pitfalls.md) |
+| GitHub Copilot agent firewall        | [copilot-agent-firewall.md](./copilot-agent-firewall.md)    |
 | Testing conventions and practices    | [testing/](./testing/)                                       |
 
 ## 🚀 Getting Started

docs/contributing/copilot-agent-firewall.md

@@ -0,0 +1,207 @@
+# GitHub Copilot Agent Firewall Configuration
+
+This document describes the firewall configuration for GitHub Copilot coding agent in this repository and provides guidance for future maintenance.
+
+## Overview
+
+The GitHub Copilot coding agent operates in a restricted environment with a firewall that blocks external network access by default. This configuration is necessary to allow the agent to install project dependencies using the [dependency-installer](../../packages/dependency-installer/README.md) tool.
+
+## Current Configuration
+
+### Firewall Status
+
+- **Firewall**: ✅ Enabled (recommended for security)
+- **Recommended Allowlist**: ✅ Enabled (pre-configured common repositories)
+- **Custom Allowlist**: ✅ Configured (project-specific domains)
+
+### Custom Allowlist Domains
+
+The following domains have been added to the custom allowlist:
+
+#### opentofu.org
+
+- **Purpose**: OpenTofu installation
+- **Used By**: `packages/dependency-installer/src/installer/opentofu.rs`
+- **Rationale**: Downloads OpenTofu installer script from `get.opentofu.org` and installation packages
+- **Subdomain Coverage**: Allows traffic to all subdomains (e.g., `get.opentofu.org`)
+- **Date Added**: November 5, 2025
+- **Added By**: Repository administrator
+
+### Domains Covered by Recommended Allowlist
+
+The following dependencies are automatically allowed through GitHub's recommended allowlist and do **not** require custom configuration:
+
+#### Package Repositories
+
+- **Ubuntu/Debian APT Repositories**: Used by Ansible installer (`apt-get install ansible`)
+- **Rust Package Registry (crates.io)**: Used by cargo-machete installer (`cargo install cargo-machete`)
+- **Snap Store**: Used by LXD installer (`snap install lxd`)
+
+These are included in GitHub's default recommended allowlist which covers common package repositories, container registries, and certificate authorities.
+
+## Configuration Steps
+
+### Prerequisites
+
+- Repository admin access required
+- Must be logged into GitHub
+
+### Step-by-Step Instructions
+
+1. Navigate to repository settings:
+
+   ```text
+   https://github.com/torrust/torrust-tracker-deployer/settings
+   ```
+
+2. In the sidebar under "Code & automation", click:
+   - **Copilot** → **coding agent**
+
+3. Verify firewall settings:
+   - ✅ Ensure **Enable firewall** is toggled ON
+   - ✅ Ensure **Recommended allowlist** is toggled ON
+
+4. Configure custom allowlist:
+   - Click **Custom allowlist**
+   - In the "Add domain" field, enter: `opentofu.org`
+   - Click **Add Rule**
+   - Click **Save changes**
+
+5. Verify configuration:
+   - The custom allowlist should now show `opentofu.org`
+   - Firewall and recommended allowlist should remain enabled
+
+## Domain vs URL Rules
+
+When configuring the custom allowlist, you can add either domains or specific URLs:
+
+- **Domain** (e.g., `opentofu.org`):
+  - ✅ Allows traffic to the domain **and all subdomains**
+  - ✅ Recommended for most cases
+  - Example: `opentofu.org` allows both `get.opentofu.org` and `packages.opentofu.org`
+
+- **URL** (e.g., `https://get.opentofu.org/installer/`):
+  - ⚠️ Only allows specified scheme, host, and path
+  - ⚠️ More restrictive, harder to maintain
+  - Use only when you need to restrict to specific paths
+
+**Recommendation**: Use domain rules for flexibility and easier maintenance.
+
+## Security Considerations
+
+### Best Practices
+
+1. ✅ **Keep firewall enabled** - Protects against data exfiltration
+2. ✅ **Keep recommended allowlist enabled** - Covers common package repositories
+3. ✅ **Use minimal custom allowlist** - Only add domains that are absolutely necessary
+4. ✅ **Document each domain** - Explain why each domain is needed
+5. ❌ **Never disable the firewall** - Increases security risks significantly
+
+### Limitations
+
+From GitHub documentation, the Copilot agent firewall has the following limitations:
+
+- **Scope**: Only applies to processes started by the agent via its Bash tool
+- **Not Applied To**:
+  - Model Context Protocol (MCP) servers
+  - Processes started in configured Copilot setup steps
+- **Security Note**: Sophisticated attacks may bypass the firewall
+- **Environment**: Only operates within GitHub Actions appliance environment
+
+For more details, see [GitHub's official documentation](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/customize-the-agent-firewall).
+
+## Testing Firewall Configuration
+
+After adding a domain to the allowlist, verify that the dependency installer can access it:
+
+```bash
+# Test OpenTofu installation
+cargo run --bin dependency-installer install --dependency opentofu
+
+# Expected result: Installation should succeed without DNS resolution errors
+# Before configuration: "curl: (6) Could not resolve host: get.opentofu.org"
+# After configuration: Installation completes successfully
+```
+
+## Future Maintenance
+
+### Adding New Domains
+
+When adding new dependency installers that require external network access:
+
+1. **Test First**: Run the installer in the Copilot agent environment
+2. **Check for Errors**: Look for DNS resolution or connection failures
+3. **Identify Domain**: Determine which domain needs to be whitelisted
+4. **Add to Allowlist**: Follow the configuration steps above
+5. **Update Documentation**: Add the new domain to this document with:
+   - Purpose and rationale
+   - Which installer uses it
+   - Date added and who added it
+6. **Test Again**: Verify the installer now works
+7. **Update Issue Spec**: Update [issue #147 specification](../issues/147-1-7-configure-copilot-agent-firewall-for-dependency-installer.md) if needed
+
+### Troubleshooting Common Issues
+
+#### DNS Resolution Errors
+
+```bash
+curl: (6) Could not resolve host: example.com
+```
+
+**Solution**: Add `example.com` to the custom allowlist.
+
+#### Connection Refused Errors
+
+```bash
+curl: (7) Failed to connect to example.com port 443: Connection refused
+```
+
+**Possible Causes**:
+
+- Domain not in allowlist (add it)
+- Service is down (check service status)
+- Wrong port/protocol (verify URL)
+
+#### Subdomain Access Issues
+
+If you added `example.com` but `api.example.com` is still blocked:
+
+**Solution**: Domain rules should cover subdomains. Verify:
+
+- Domain was added correctly (not as a URL)
+- Changes were saved
+- Try again after a few minutes (changes may take time to propagate)
+
+## Related Documentation
+
+### GitHub Documentation
+
+- [Customizing the agent firewall](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/customize-the-agent-firewall)
+- [Preinstalling tools in Copilot's environment](https://docs.github.com/en/copilot/customizing-copilot/customizing-the-development-environment-for-copilot-coding-agent#preinstalling-tools-in-copilots-environment)
+
+### Project Documentation
+
+- [Dependency Installer Package](../../packages/dependency-installer/README.md)
+- [E2E Testing Guide](../e2e-testing.md)
+- [Issue #147 Specification](../issues/147-1-7-configure-copilot-agent-firewall-for-dependency-installer.md)
+- [Issue #146 - Update Pre-Commit Script](../issues/146-1-6-update-precommit-script-for-github-runner-compatible-e2e-tests.md)
+
+## History
+
+### Configuration Changes
+
+| Date | Change | Added By | Rationale |
+|------|--------|----------|-----------|
+| 2025-11-05 | Added `opentofu.org` | Repository administrator | Enable OpenTofu installation for dependency-installer tool |
+
+### Documentation Changes
+
+| Date | Change | Author |
+|------|--------|--------|
+| 2025-11-05 | Initial documentation | GitHub Copilot Agent |
+
+## Notes
+
+- This configuration was created as part of [Issue #147](https://github.com/torrust/torrust-tracker-deployer/issues/147)
+- Parent epic: [Issue #112 - Refactor and Improve E2E Test Execution](https://github.com/torrust/torrust-tracker-deployer/issues/112)
+- Repository settings modifications require admin access and cannot be performed by Copilot agent

packages/dependency-installer/README.md

@@ -42,6 +42,10 @@ This package can detect and install the following development dependencies:
 - **Ansible** - Configuration management tool
 - **LXD** - VM-based testing infrastructure
 
+### GitHub Copilot Agent Requirements
+
+When running in GitHub Copilot agent environment, network access to external domains is restricted by a firewall. The OpenTofu installer requires `opentofu.org` to be added to the custom allowlist. See [Copilot Agent Firewall Configuration](../../docs/contributing/copilot-agent-firewall.md) for details on configured domains and setup instructions.
+
 ## Usage
 
 ### CLI Binary