Pluggable gRPC executors blueprint

Why is this change being made?

💡 Provide a detailed answer to the question on why this change is being proposed, in accordance with our value of Transparency.

Please add the details saying why, not just what in this section. Example: We have discussed the topic in Slack - (copy of Slack conversation). The current process is not efficient, this MR makes the description of X more clear, and helps move Y forward.

This MR adds the "GitLab Runner Pluggable gRPC Executors" design document to the GitLab handbook. This blueprint proposes a fundamental architectural transformation of GitLab Runner from a monolithic executor framework to a pluggable gRPC executor architecture.

Why this change is needed:

GitLab Runner's current monolithic architecture presents several limitations that this design addresses:

1. Limited Extensibility: Users requiring custom execution environments must modify GitLab Runner source code or use the limited "custom executor" which lacks native integration with GitLab features
2. Monolithic Coupling: All executor logic is embedded within the GitLab Runner binary, making it difficult to add new executor types or maintain independent versioning cycles
3. Policy Enforcement Gaps: Administrators have limited ability to enforce organizational policies on job execution environments
4. Configuration Complexity: The runner configuration has become increasingly complex with limited validation capabilities

What this blueprint enables:

• Decoupled Architecture: Replace built-in executors (Kubernetes, Docker, Shell, etc.) with standalone gRPC plugins
• Three Plugin Types: Support local, autoscaled, and kubernetes plugin architectures for different execution patterns
• Enhanced Extensibility: Enable users to write custom executors that integrate seamlessly with GitLab's CI/CD pipeline
• Cross-Platform Support: Plugin development across Linux, Windows, and macOS using HashiCorp go-plugin framework
• Backward Compatibility: Ensure existing GitLab Runner configurations continue to work without modification

This design document includes proof-of-concept implementations demonstrating the feasibility of the approach, with working examples of executor plugins using Arran's interface design. The blueprint serves as the foundation for future GitLab Runner architecture evolution and provides a clear path for implementation.

Author and Reviewer Checklist

Please verify the check list and ensure to tick them off before the MR is merged.

• Provided a concise title for this Merge Request (MR)
• Added a description to this MR explaining the reasons for the proposed change, per say why, not just what
  • Copy/paste the Slack conversation to document it for later, or upload screenshots. Verify that no confidential data is added, and the content is SAFE
• Assign reviewers for this MR to the correct
  • The when to get approval handbook section explains when DRI approval is required
  • The who can approve handbook section explains how to identify the DRI
  • If the MR does not require DRI approval, consider asking someone on your team, such as your manager.
  • The approver may merge the MR. If they approve but don't merge, you can merge.
• For transparency, share this MR with the audience that will be impacted.
  • Team: For changes that affect your direct team, share in your group Slack channel
  • Department: If the update affects your department, share the MR in your department Slack channel
  • Division: If the update affects your division, share the MR in your division Slack channel
  • Company: If the update affects all (or the majority of) GitLab team members, post an update in #whats-happening-at-gitlab linking to this MR
    • For high-priority company-wide announcements work with the internal communications team to post the update in #company-fyi and align on a plan to circulate in additional channels like the "While You Were Iterating" Newsletter

Commits

• Add pluggable gRPC executors blueprint

---