@htekdev/actions-debugger 1.0.56 → 1.0.57

package/errors/permissions-auth/permissions-auth-041.yml

@@ -0,0 +1,110 @@
+id: permissions-auth-041
+title: "actions/checkout submodules fail with auth error when private submodule repos are outside the workflow repository"
+category: permissions-auth
+severity: error
+tags:
+  - checkout
+  - submodules
+  - github-token
+  - private-repo
+  - authentication
+  - pat
+  - deploy-key
+patterns:
+  - regex: 'fatal: could not read Username for.*terminal prompts disabled'
+    flags: 'i'
+  - regex: 'fatal: repository ''.*github\.com.*'' not found'
+    flags: 'i'
+  - regex: 'remote: Repository not found\.'
+    flags: 'i'
+  - regex: 'Error: The process.*git.*failed with exit code 128'
+    flags: 'i'
+error_messages:
+  - "fatal: could not read Username for 'https://github.com': terminal prompts disabled"
+  - "fatal: repository 'https://github.com/org/private-submodule/' not found"
+  - "remote: Repository not found."
+  - "Error: The process '/usr/bin/git' failed with exit code 128"
+root_cause: |
+  `actions/checkout` uses the `GITHUB_TOKEN` (or the `token` input) to authenticate
+  git operations during checkout, including recursive submodule initialization.
+  `GITHUB_TOKEN` is automatically scoped to the repository that owns the running
+  workflow — it cannot access private repositories in other organizations, or other
+  private repositories within the same organization.
+
+  When a submodule `.gitmodules` entry points to a private repository that is different
+  from the workflow repository, git authentication fails during `submodule update`.
+  The resulting error (`fatal: could not read Username` or `repository not found`)
+  is confusing because the submodule URL is correct — the problem is authentication
+  scope, not the URL itself.
+
+  Developers upgrading from self-hosted runners (where global git credentials were
+  configured) or from `actions/checkout@v1-v2` (which had different authentication
+  behavior) frequently encounter this when moving to `actions/checkout@v4` on
+  GitHub-hosted runners.
+
+  This is a deliberate security boundary: `GITHUB_TOKEN` is intentionally limited to
+  the current repository to prevent workflows from silently reading other private repos.
+fix: |
+  Use one of two approaches:
+
+  1. **PAT approach**: Create a Personal Access Token (classic PAT with `repo` scope,
+     or a fine-grained PAT with read access to all submodule repos). Store it as a
+     repository secret and pass it via the `token` input to `actions/checkout`.
+
+  2. **Deploy key approach**: Add a read-only deploy key to each private submodule
+     repository, then use `webfactory/ssh-agent` to load the key before checkout.
+     This avoids PATs entirely and follows least-privilege principles.
+
+  For organizations, a machine account (a GitHub account created for automation) with
+  `repo` read access to all submodule repos is often easier to manage than fine-grained
+  PATs.
+fix_code:
+  - language: yaml
+    label: "PAT with repo scope passed via token input"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                submodules: recursive
+                token: ${{ secrets.SUBMODULE_PAT }}
+                # SUBMODULE_PAT: classic PAT with repo scope, or fine-grained PAT
+                # with Contents: read on all private submodule repos
+
+  - language: yaml
+    label: "SSH deploy key approach using webfactory/ssh-agent"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Configure SSH agent with submodule deploy key
+              uses: webfactory/ssh-agent@v0.9.0
+              with:
+                ssh-private-key: ${{ secrets.SUBMODULE_DEPLOY_KEY }}
+                # Add multiple keys for multiple private submodule repos:
+                # ssh-private-key: |
+                #   ${{ secrets.SUBMODULE_REPO_A_KEY }}
+                #   ${{ secrets.SUBMODULE_REPO_B_KEY }}
+
+            - uses: actions/checkout@v4
+              with:
+                submodules: recursive
+                # No token needed — SSH agent handles git authentication
+prevention:
+  - "Prefer deploy keys over PATs for submodule access — deploy keys are repo-scoped and easier to rotate"
+  - "Use fine-grained PATs scoped to specific repositories rather than classic PATs with broad repo scope"
+  - "Document which submodule repos require special secrets so new contributors can configure their forks"
+  - "Consider converting private submodule dependencies to private packages in a registry to avoid cross-repo auth complexity"
+  - "Test submodule checkout in a fresh fork or on a runner without existing git credentials to catch auth issues early"
+docs:
+  - url: "https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication#permissions-for-the-github_token"
+    label: "GitHub Docs — GITHUB_TOKEN permissions and scope"
+  - url: "https://github.com/actions/checkout#usage"
+    label: "actions/checkout — token and submodules inputs"
+  - url: "https://docs.github.com/en/authentication/connecting-to-github-with-ssh/managing-deploy-keys"
+    label: "GitHub Docs — Managing deploy keys"
+  - url: "https://github.com/webfactory/ssh-agent"
+    label: "webfactory/ssh-agent — Load SSH keys for Actions"

package/errors/runner-environment/runner-environment-112.yml

@@ -0,0 +1,98 @@
+id: runner-environment-112
+title: "ubuntu-24.04 nftables replaces iptables — Docker bridge networking and kind/minikube cluster setup fails"
+category: runner-environment
+severity: error
+tags:
+  - ubuntu-24.04
+  - docker
+  - networking
+  - iptables
+  - nftables
+  - kind
+  - minikube
+  - runner-image-update
+patterns:
+  - regex: 'No chain/target/match by that name'
+    flags: 'i'
+  - regex: 'iptables.*failed.*nat.*DOCKER'
+    flags: 'i'
+  - regex: 'Failed to set up iptables.*\(iptables-nft\)'
+    flags: 'i'
+  - regex: 'network.*setup.*failed.*iptables'
+    flags: 'i'
+  - regex: 'Error response from daemon.*iptables failed'
+    flags: 'i'
+error_messages:
+  - "iptables: No chain/target/match by that name."
+  - "Error response from daemon: driver failed programming external connectivity on endpoint: iptables failed: iptables --wait -t nat -A DOCKER -p tcp -d 0/0 --dport 5432 -j DNAT --to-destination 172.17.0.2:5432 ! -i docker0: iptables: No chain/target/match by that name."
+  - "Failed to set up iptables rules: iptables-nft is not supported"
+  - "Error: failed to create cluster: failed to ensure docker network: failed to set up kind CNI"
+root_cause: |
+  Ubuntu 24.04 ships with nftables as the primary packet-filtering framework. The `iptables`
+  command is now a thin wrapper around nftables (`iptables-nft`), replacing the legacy
+  `iptables-legacy` backend that was default on Ubuntu 20.04/22.04.
+
+  Docker's bridge networking writes iptables rules using legacy format assumptions. CNI plugins
+  used by Kubernetes tools (kind, minikube, k3s) also expect the legacy iptables backend to be
+  active. When these tools run on ubuntu-24.04, they encounter incompatible chain formats and
+  rule semantics that iptables-nft does not honour, causing network setup to fail with "No
+  chain/target/match by that name" errors.
+
+  The runner-images migration from ubuntu-22.04 to ubuntu-24.04 (and from ubuntu-latest pointing
+  to ubuntu-22.04 to ubuntu-24.04) silently exposes this issue for any workflow running
+  Docker-in-Docker, Kubernetes clusters, or service containers with custom networking.
+fix: |
+  Switch the `iptables` alternative back to the legacy backend before starting Docker or
+  any CNI-based tooling. Add this step at the top of your job, before any Docker or cluster
+  setup steps:
+
+    - name: Switch to legacy iptables
+      run: |
+        sudo update-alternatives --set iptables /usr/sbin/iptables-legacy
+        sudo update-alternatives --set ip6tables /usr/sbin/ip6tables-legacy
+
+  For kind clusters, the above fix is the most reliable approach.
+
+  If you cannot switch the iptables backend (e.g., you require nftables for other reasons),
+  use Docker with `--iptables=false` and manage forwarding rules manually, or use network
+  mode `host` where possible.
+
+  Long-term: upgrade to versions of kind (≥ v0.24), minikube (≥ v1.33), and Docker Engine
+  (≥ 27) that include nftables-native support.
+fix_code:
+  - language: yaml
+    label: "Switch to iptables-legacy before Docker or cluster setup (ubuntu-24.04)"
+    code: |
+      jobs:
+        test:
+          runs-on: ubuntu-24.04
+          steps:
+            - name: Switch to legacy iptables
+              run: |
+                sudo update-alternatives --set iptables /usr/sbin/iptables-legacy
+                sudo update-alternatives --set ip6tables /usr/sbin/ip6tables-legacy
+
+            - name: Start kind cluster
+              uses: helm/kind-action@v1
+              with:
+                cluster_name: ci
+  - language: yaml
+    label: "Pin runs-on to ubuntu-22.04 as a temporary workaround"
+    code: |
+      jobs:
+        test:
+          # Temporary: ubuntu-22.04 uses iptables-legacy by default
+          # TODO: migrate to ubuntu-24.04 after updating kind/Docker versions
+          runs-on: ubuntu-22.04
+prevention:
+  - "Test workflows on ubuntu-24.04 explicitly before relying on ubuntu-latest switching to it"
+  - "Keep kind, minikube, and Docker Engine versions current — nftables-native support arrived in each"
+  - "Add an iptables-legacy switch step as a defensive measure in any job using Docker networking or CNI plugins"
+  - "Watch runner-images release notes (github.com/actions/runner-images) for ubuntu-latest label changes"
+docs:
+  - url: "https://docs.docker.com/network/iptables/"
+    label: "Docker — iptables and nftables networking"
+  - url: "https://github.com/actions/runner-images/issues/10636"
+    label: "runner-images #10636 — ubuntu-24.04 iptables-nft Docker incompatibility"
+  - url: "https://kind.sigs.k8s.io/docs/user/known-issues/"
+    label: "kind — Known Issues including iptables compatibility"

package/errors/runner-environment/runner-environment-113.yml

@@ -0,0 +1,118 @@
+id: runner-environment-113
+title: "ubuntu-24.04 removed python3-distutils — ModuleNotFoundError: No module named 'distutils' on pip install"
+category: runner-environment
+severity: error
+tags:
+  - ubuntu-24.04
+  - python
+  - distutils
+  - pip
+  - setup-py
+  - runner-image-update
+  - python-3-12
+patterns:
+  - regex: "ModuleNotFoundError: No module named 'distutils'"
+    flags: 'i'
+  - regex: 'No module named ''distutils\.core'''
+    flags: 'i'
+  - regex: 'error in setup command.*distutils'
+    flags: 'i'
+  - regex: 'distutils.*not found.*pip install'
+    flags: 'i'
+error_messages:
+  - "ModuleNotFoundError: No module named 'distutils'"
+  - "ModuleNotFoundError: No module named 'distutils.core'"
+  - "error in setup command: Error parsing /path/to/setup.cfg: No module named 'distutils.core'"
+  - "note: This error originates from a subprocess, and is likely not a problem with pip."
+  - "error: legacy-install-failure"
+root_cause: |
+  Ubuntu 24.04 ships Python 3.12 as the system Python. Python 3.12 fully removed the
+  `distutils` module from its standard library (it was deprecated in 3.10 and removed in 3.12
+  per PEP 632). Ubuntu Noble (24.04) also removed the `python3-distutils` apt backport package
+  that had been available on 20.04 and 22.04.
+
+  Many older Python packages still use `distutils` directly in their `setup.py` or `setup.cfg`
+  files. When `pip install` processes these packages, the build backend invokes `distutils` which
+  is no longer available. The error appears to be a build backend failure rather than a pip
+  failure, so the root cause is easy to miss.
+
+  This affects any workflow that:
+  - Uses the system Python (no `actions/setup-python` step)
+  - Installs packages with legacy `setup.py` that import `distutils`
+  - Creates virtualenvs from the system Python without pre-installing setuptools
+
+  Distinct from `setup-python-version-range-resolves-to-313-distutils-removed` which covers
+  setup-python action resolving to Python 3.12/3.13 and distutils in user packages. This entry
+  covers the apt-level removal affecting system Python on the ubuntu-24.04 runner image itself.
+fix: |
+  Option 1 (recommended): Use actions/setup-python to manage the Python version explicitly.
+  setup-python bundles setuptools which provides a distutils compatibility shim.
+
+  Option 2: Install setuptools as the first pip action before installing other packages.
+  setuptools >= 58.0.0 ships a `distutils` compatibility shim that satisfies `import distutils`.
+
+    - name: Install setuptools (distutils shim)
+      run: pip install setuptools
+
+  Option 3: Install the apt package `python3-setuptools` which restores distutils compatibility
+  at the system level for Python 3.12.
+
+  Option 4 (long-term): Migrate the affected package to PEP 517/518 — replace setup.py with
+  pyproject.toml and a modern build backend (setuptools>=61, flit, hatch, etc.).
+fix_code:
+  - language: yaml
+    label: "Use actions/setup-python so setuptools is available (recommended)"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-24.04
+          steps:
+            - uses: actions/checkout@v4
+
+            - uses: actions/setup-python@v5
+              with:
+                python-version: '3.12'
+
+            - name: Install dependencies
+              run: pip install -r requirements.txt
+  - language: yaml
+    label: "Pre-install setuptools to restore distutils shim (quick fix for system Python)"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-24.04
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Install setuptools (distutils compatibility shim for Python 3.12)
+              run: pip install --upgrade setuptools
+
+            - name: Install dependencies
+              run: pip install -r requirements.txt
+  - language: yaml
+    label: "Install python3-setuptools via apt (system-level fix)"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-24.04
+          steps:
+            - name: Install python3-setuptools
+              run: sudo apt-get install -y python3-setuptools
+
+            - name: Install dependencies
+              run: pip install -r requirements.txt
+prevention:
+  - "Always use actions/setup-python rather than relying on system Python — it ships with setuptools"
+  - "Pin a Python version explicitly; avoid implicit system Python which changes per runner image"
+  - "Run pip install --dry-run in CI to detect distutils/setuptools issues before they block builds"
+  - "Audit third-party dependencies for setup.py usage with: pip install pipdeptree; pipdeptree | grep setup.py"
+  - "Migrate legacy setup.py packages to pyproject.toml for long-term Python 3.12+ compatibility"
+docs:
+  - url: "https://docs.python.org/3/whatsnew/3.12.html#removed"
+    label: "Python 3.12 — Removed modules (distutils)"
+  - url: "https://peps.python.org/pep-0632/"
+    label: "PEP 632 — Deprecate distutils"
+  - url: "https://github.com/actions/runner-images/issues/9674"
+    label: "runner-images #9674 — python3-distutils unavailable on ubuntu-24.04"
+  - url: "https://github.com/actions/setup-python"
+    label: "actions/setup-python — bundles setuptools"

package/errors/runner-environment/runner-environment-114.yml

@@ -0,0 +1,130 @@
+id: runner-environment-114
+title: "macOS-26 / Xcode 26 defaults to Swift 6 strict concurrency — existing Swift builds fail with actor isolation errors"
+category: runner-environment
+severity: error
+tags:
+  - macos-26
+  - xcode-26
+  - swift-6
+  - concurrency
+  - actor-isolation
+  - runner-image-update
+  - breaking-change
+patterns:
+  - regex: "error: sending '.*' to actor-isolated"
+    flags: 'i'
+  - regex: 'actor-isolated.*cannot.*referenced from.*non-isolated'
+    flags: 'i'
+  - regex: "error: '.*' cannot be used to satisfy the '@Sendable' requirement"
+    flags: 'i'
+  - regex: 'error:.*Sendable.*cannot conform.*in Swift 6'
+    flags: 'i'
+  - regex: 'main actor-isolated.*cannot be referenced from.*nonisolated'
+    flags: 'i'
+error_messages:
+  - "error: sending 'self' to actor-isolated initializer 'init()' risks causing data races"
+  - "error: actor-isolated property 'delegate' can not be referenced from a non-isolated context"
+  - "error: main actor-isolated class method 'viewDidLoad()' cannot be referenced from a nonisolated context"
+  - "error: 'Sendable'-conforming class 'MyViewController' cannot inherit from another class other than 'NSObject'"
+  - "error: expression is 'async' but is not marked with 'await'"
+root_cause: |
+  Xcode 26 (shipped with the macos-26 runner) defaults to Swift 6 language mode. Previous
+  Xcode versions (14, 15, 16) compiled in Swift 5 compatibility mode by default, which did not
+  enforce strict data-race safety checking.
+
+  Swift 6 enforces complete concurrency checking at compile time:
+  - All values shared across actor boundaries must conform to `Sendable`
+  - Calls to `@MainActor`-isolated methods from non-isolated contexts must be `await`-ed
+  - Closures passed to async contexts must be `@Sendable`
+  - Class hierarchies that cross actor boundaries require explicit `Sendable` conformance
+
+  Code that compiled and ran correctly under Swift 5 may produce dozens of compiler errors in
+  Swift 6, even if it had no actual concurrency bugs. The errors are not warnings — they are
+  hard build failures.
+
+  The macos-26 runner ships Xcode 26 as the default Xcode. Any workflow running `xcodebuild`
+  or `swift build` without an explicit Swift language version flag will pick up Swift 6.
+fix: |
+  Short-term: Pin to Swift 5 compatibility mode in your build command or project settings.
+
+  Option A — xcodebuild flag:
+    xcodebuild build -scheme MyScheme SWIFT_VERSION=5
+
+  Option B — Xcode build settings (xcconfig or project settings):
+    SWIFT_VERSION = 5
+
+  Option C — Package.swift swift-tools-version (for Swift Package Manager projects):
+    Change the first line to: // swift-tools-version: 5.10
+    This sets the package manifest version and implicitly enables Swift 5 mode for dependencies.
+
+  Option D — Per-target in Package.swift:
+    .target(name: "MyTarget", swiftSettings: [.unsafeFlags(["-swift-version", "5"])])
+
+  Long-term: Migrate your codebase to Swift 6 concurrency model by resolving actor isolation
+  errors. Apple provides a migration guide at developer.apple.com/documentation/swift/migrating-to-swift-6.
+fix_code:
+  - language: yaml
+    label: "Pin SWIFT_VERSION=5 in xcodebuild to restore Swift 5 compatibility on macos-26"
+    code: |
+      jobs:
+        build:
+          runs-on: macos-26
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Build (Swift 5 compatibility mode)
+              run: |
+                xcodebuild build \
+                  -scheme MyApp \
+                  -destination 'platform=macOS' \
+                  SWIFT_VERSION=5
+
+            - name: Test (Swift 5 compatibility mode)
+              run: |
+                xcodebuild test \
+                  -scheme MyApp \
+                  -destination 'platform=macOS' \
+                  SWIFT_VERSION=5
+  - language: yaml
+    label: "Pin swift-tools-version in Package.swift for SPM projects"
+    code: |
+      # In Package.swift — change the first line to request Swift 5 tools:
+      # // swift-tools-version: 5.10
+      #
+      # Then in the workflow:
+      jobs:
+        build:
+          runs-on: macos-26
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Build Swift package
+              run: swift build -c release
+  - language: yaml
+    label: "Temporarily pin to macos-15 while migrating to Swift 6"
+    code: |
+      jobs:
+        build:
+          # TODO: Migrate to Swift 6 and update to macos-26
+          # Track progress at: <link to your Swift 6 migration issue>
+          runs-on: macos-15
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Build
+              run: xcodebuild build -scheme MyApp -destination 'platform=macOS'
+prevention:
+  - "Test workflows on macos-26 before relying on macos-latest switching to it"
+  - "Specify SWIFT_VERSION explicitly in Xcode project settings rather than relying on Xcode defaults"
+  - "Enable strict concurrency warnings (SWIFT_STRICT_CONCURRENCY=complete) in Swift 5 mode to preview Swift 6 errors before migrating"
+  - "Watch github.com/actions/runner-images release notes for macos-latest label changes"
+  - "Pin swift-tools-version in Package.swift to document the intended Swift compatibility level"
+docs:
+  - url: "https://developer.apple.com/documentation/swift/migrating-to-swift-6"
+    label: "Apple Developer — Migrating to Swift 6"
+  - url: "https://www.swift.org/migration/documentation/swift-6-concurrency-migration-guide/"
+    label: "Swift.org — Swift 6 Concurrency Migration Guide"
+  - url: "https://github.com/actions/runner-images/blob/main/images/macos/macos-26-Readme.md"
+    label: "runner-images — macOS 26 image README (Xcode default version)"
+  - url: "https://developer.apple.com/documentation/xcode-release-notes"
+    label: "Xcode Release Notes — Xcode 26 language defaults"

package/errors/runner-environment/runner-environment-115.yml

@@ -0,0 +1,120 @@
+id: runner-environment-115
+title: "ubuntu-22.04/24.04 OpenSSL 3 disables legacy TLS renegotiation — SSL handshake failures connecting to legacy servers"
+category: runner-environment
+severity: error
+tags:
+  - ubuntu-22.04
+  - ubuntu-24.04
+  - openssl-3
+  - tls
+  - ssl
+  - renegotiation
+  - runner-image-update
+  - networking
+patterns:
+  - regex: 'unsafe legacy renegotiation disabled'
+    flags: 'i'
+  - regex: 'SSL_ERROR_RX_UNEXPECTED_HELLO_REQUEST'
+    flags: 'i'
+  - regex: 'error:0A000179:SSL routines.*unsafe legacy renegotiation'
+    flags: 'i'
+  - regex: 'UNSAFE_LEGACY_RENEGOTIATION_DISABLED'
+    flags: 'i'
+  - regex: 'ssl.*renegotiation.*not allowed'
+    flags: 'i'
+error_messages:
+  - "error:0A000179:SSL routines::unsafe legacy renegotiation disabled"
+  - "SSL_ERROR_RX_UNEXPECTED_HELLO_REQUEST"
+  - "ssl.SSLError: [SSL: UNSAFE_LEGACY_RENEGOTIATION_DISABLED] unsafe legacy renegotiation disabled (_ssl.c:997)"
+  - "OpenSSL Error: error:0A000179:SSL routines:ssl3_read_bytes:unsafe legacy renegotiation disabled"
+  - "curl: (35) OpenSSL SSL_connect: error:0A000179:SSL routines::unsafe legacy renegotiation disabled"
+  - "java.io.IOException: Error writing to server: javax.net.ssl.SSLHandshakeException: Remote host terminated the handshake"
+root_cause: |
+  Ubuntu 22.04 and 24.04 ship OpenSSL 3.0+. OpenSSL 3.0 enforces RFC 5746 (TLS Renegotiation
+  Indication Extension) by default and rejects connections to TLS servers that do not advertise
+  support for secure renegotiation in the initial ClientHello/ServerHello handshake.
+
+  Servers compiled against older OpenSSL (< 0.9.8m) or certain embedded TLS stacks do not send
+  the `renegotiation_info` extension and are therefore rejected by OpenSSL 3.0 clients with
+  `UNSAFE_LEGACY_RENEGOTIATION_DISABLED`.
+
+  This commonly surfaces when:
+  - Workflows connect to internal/staging HTTPS servers running old TLS stacks
+  - docker-compose services use self-signed certs from outdated libraries
+  - gRPC clients compiled against old OpenSSL connect to legacy gRPC servers
+  - curl/wget calls target third-party APIs that have not updated their TLS handshake
+  - Java HTTPS tests connect to embedded Jetty/Netty servers with old SSL config
+
+  The error did not occur on ubuntu-20.04 (OpenSSL 1.1.1, which allowed legacy renegotiation
+  by default). Workflows migrating from ubuntu-20.04 to 22.04/24.04 encounter it for the first
+  time.
+fix: |
+  Option 1 (recommended for CI): Append `UnsafeLegacyRenegotiation = true` to the OpenSSL
+  config file at the start of the job. This is acceptable in CI/testing contexts where you
+  control the environment; never use this in production.
+
+  Option 2: Set OPENSSL_CONF to /dev/null to bypass the OpenSSL configuration file entirely.
+  Use only for quick diagnostics or tests against known internal servers.
+
+  Option 3 (recommended long-term): Upgrade the legacy server's TLS library so it advertises
+  RFC 5746 support. For embedded test servers, upgrade the underlying HTTP/TLS library version.
+
+  Option 4: Use `curl --no-sessionid` or `curl --legacy-renegotiation` (curl 7.83+) for
+  specific curl-based steps without affecting the whole environment.
+fix_code:
+  - language: yaml
+    label: "Enable UnsafeLegacyRenegotiation in OpenSSL config for CI (workaround)"
+    code: |
+      jobs:
+        integration-test:
+          runs-on: ubuntu-24.04
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Allow legacy TLS renegotiation (CI workaround for legacy test servers)
+              run: |
+                echo "Options = UnsafeLegacyRenegotiation" | \
+                  sudo tee -a /etc/ssl/openssl.cnf
+
+            - name: Run integration tests
+              run: npm test
+  - language: yaml
+    label: "Override OPENSSL_CONF per-step (minimal blast radius)"
+    code: |
+      jobs:
+        integration-test:
+          runs-on: ubuntu-24.04
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Test against legacy HTTPS endpoint
+              env:
+                OPENSSL_CONF: /dev/null
+              run: |
+                curl -v https://legacy-test-server.internal/health
+  - language: yaml
+    label: "Set OPENSSL_CONF at job level (affects all steps)"
+    code: |
+      jobs:
+        integration-test:
+          runs-on: ubuntu-24.04
+          env:
+            OPENSSL_CONF: /dev/null
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm test
+prevention:
+  - "Upgrade internal/staging test servers to modern TLS libraries that support RFC 5746"
+  - "Use `openssl s_client -connect host:443` in CI to detect legacy renegotiation issues before they block builds"
+  - "Avoid pinning to ubuntu-20.04 as a permanent workaround — it reached EOL and will be removed from runner images"
+  - "When upgrading from ubuntu-20.04 to 22.04/24.04, run a connectivity smoke-test against all HTTPS endpoints the workflow touches"
+  - "Use testcontainers or modern embedded test server libraries that ship up-to-date TLS stacks"
+docs:
+  - url: "https://www.openssl.org/docs/man3.0/man3/SSL_CTX_set_options.html"
+    label: "OpenSSL 3.0 — SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION option"
+  - url: "https://github.com/actions/runner-images/issues/6399"
+    label: "runner-images #6399 — OpenSSL 3 renegotiation issues on ubuntu-22.04"
+  - url: "https://github.com/openssl/openssl/issues/17593"
+    label: "OpenSSL #17593 — Legacy renegotiation rejection in 3.0"
+  - url: "https://www.rfc-editor.org/rfc/rfc5746"
+    label: "RFC 5746 — TLS Renegotiation Indication Extension"