Support for Defining Default Docker Network via Repository Settings and Environment Variables (Without Elevated Trust)

[JakobEichler]

Clear and concise description of the problem

Hi Woodpecker team 👋,

I'd like to suggest a feature to enhance control and security around Docker networking for build containers: the ability to define a default Docker network, both on a per-repository basis and via a global environment variable — without requiring elevated trust.

---

This would simplify restricting network access of services in docker-containers to woodpecker-build-containers.

---

🔍 Current Behavior

Currently, it's possible to assign a network to build containers using the network_mode setting in .woodpecker.yml, but this requires the repository to be marked as trusted.

This introduces a few limitations:

• It increases the privilege requirements for repositories, which may not be acceptable in open or shared environments.
• It forces network control to reside in versioned code, rather than centrally by CI administrators.
• Build containers may be connected to multiple networks (e.g., the Docker bridge and the specified one), increasing complexity.

---

Suggested solution

✅ Proposed Improvement

I propose:

1. Environment variable-based control:

   Introduce a variable such as:

   WOODPECKER_BUILD_NETWORK=my-ci-network
   

   This would apply a Docker network to all build containers by default, without requiring .woodpecker.yml changes or trust elevation.

2. Repository-level configuration:

   Allow setting a default Docker network in the Woodpecker UI or API at the repository level. This way, trusted network access can be configured without modifying pipeline YAML or requiring trust elevation.

---

🔒 Benefits

• Enables secure container-to-service communication (e.g., CI builds accessing an internal Nexus, database, etc.).
• Reduces surface area by avoiding unnecessary network exposure.
• Keeps networking policy centralized rather than per-repo.
• Avoids requiring trusted: true for networking alone.
• Easier to apply firewall or iptables rules based on known CI subnet.

---

Alternative

I guess the alternative is to expose services to the internet or to hack around in the iptables which are bypassed docker if not studied carefully

Additional context

⚠️ Note on Multiple Networks

Today, setting network_mode connects the container to the specified network in addition to the default bridge network, which can lead to unintended behavior or visibility.

This setting should ideally either:

• Replace the default bridge networks with the specified ones, or

• Allow a configuration toggle to opt out of attaching the bridge network.

• I guess allowing a network setting on a repository and a global level results in the build container to be possibly in multiple networks unless we make it so that finer-level settings overwrite global ones.

---

Let me know if this sounds like a valuable addition. I’d be happy to help test or contribute to the discussion.

Thanks again for your excellent work on Woodpecker!

Validations

• Checked that the feature isn't part of the next version already [https://woodpecker-ci.org/versions]
• Read the docs.
• Check that there isn't already an issue that request the same feature to avoid creating a duplicate.