feat(buildkite): derive GitHub comment context natively

`--scm github` read its configuration solely from GITHUB_* variables, so
Buildkite users had to shim every one of them to get PR comments. Fall back to
Buildkite's own variables when the GITHUB_* equivalents are absent: PR number,
commit, branch, checkout path, commit message, build creator, and owner/repository
parsed from BUILDKITE_REPO (preferring the pipeline repository over a
contributor's fork). Explicit GITHUB_* and PR_NUMBER values still take priority,
and GitHub Enterprise remains configurable via GITHUB_API_URL.

A running Buildkite PR build maps to the supported `synchronize` comment path,
and a non-PR build maps to `push`, so event routing is unchanged. Default-branch
detection requires an actual branch name rather than treating two unset variables
as a match, which would otherwise mark any build as the default branch and
overwrite the repository baseline.

Ref: CE-379

Author: lelia

docs/ci-cd.md

@@ -81,6 +81,19 @@ steps:
       SOCKET_SECURITY_API_TOKEN: "${SOCKET_SECURITY_API_TOKEN}"
 ```
 
+The CLI reads Buildkite's native `BUILDKITE_COMMIT`, `BUILDKITE_BRANCH`,
+`BUILDKITE_PULL_REQUEST`, and `BUILDKITE_PULL_REQUEST_BASE_BRANCH` variables.
+For pull-request builds, ensure the checkout contains the base branch and the
+checked-out head commit. The CLI uses those local refs first and performs a
+targeted fetch only when a required ref or its comparison history is missing;
+it does not fetch every remote ref and tag during startup.
+
+When `--scm github` is used from Buildkite, the CLI also derives GitHub comment
+context from `BUILDKITE_REPO`, `BUILDKITE_BUILD_CHECKOUT_PATH`, and the variables
+above. Set `GH_API_TOKEN` to a GitHub token with the required repository access.
+GitHub Enterprise users should also set `GITHUB_API_URL`; GitHub.com defaults to
+`https://api.github.com`.
+
 #### Merge-base baselines in Buildkite (dynamic pipelines)
 
 Notes for using `--base-commit-sha` (see the

socketsecurity/core/scm/github.py

@@ -1,6 +1,7 @@
 import json
 import os
 import sys
+import urllib.parse
 from dataclasses import dataclass
 
 from git import Optional
@@ -34,6 +35,31 @@ class GithubConfig:
     event_action: Optional[str]
     headers: dict
 
+    @staticmethod
+    def _repository_from_buildkite() -> tuple[str, str]:
+        """Return ``(owner, repository)`` from Buildkite's Git repository URL."""
+        repository_url = (
+            # Comments and statuses belong to the pipeline/base repository,
+            # not a contributor's fork from BUILDKITE_PULL_REQUEST_REPO.
+            os.getenv("BUILDKITE_REPO")
+            or os.getenv("BUILDKITE_PULL_REQUEST_REPO")
+            or ""
+        ).strip()
+        if not repository_url:
+            return "", ""
+
+        if "://" in repository_url:
+            repository_path = urllib.parse.urlparse(repository_url).path
+        elif ":" in repository_url:
+            # SCP-style SSH URL: git@github.com:owner/repository.git
+            repository_path = repository_url.split(":", 1)[1]
+        else:
+            repository_path = repository_url
+        parts = repository_path.strip("/").removesuffix(".git").split("/")
+        if len(parts) < 2:
+            return "", ""
+        return parts[-2], parts[-1]
+
     @classmethod
     def from_env(cls, pr_number: Optional[str] = None) -> 'GithubConfig':
         """Create config from environment variables with optional overrides"""
@@ -42,42 +68,91 @@ def from_env(cls, pr_number: Optional[str] = None) -> 'GithubConfig':
             log.error("Unable to get Github API Token from GH_API_TOKEN")
             sys.exit(2)
 
-        # Use provided PR number if available, otherwise fall back to env var
+        is_buildkite = os.getenv("BUILDKITE") == "true"
+        buildkite_pr = os.getenv("BUILDKITE_PULL_REQUEST")
+        is_buildkite_pr = bool(
+            is_buildkite
+            and buildkite_pr
+            and buildkite_pr.casefold() != "false"
+        )
+
+        # Use explicit/GitHub-compatible values first, then native Buildkite PR context.
         pr_number = pr_number or os.getenv('PR_NUMBER')
+        if not pr_number and is_buildkite_pr:
+            pr_number = buildkite_pr
 
         # Add debug logging
-        sha = os.getenv('GITHUB_SHA', '')
-        log.debug(f"Loading SHA from GITHUB_SHA: {sha}")
+        sha = os.getenv('GITHUB_SHA') or (
+            os.getenv("BUILDKITE_COMMIT", "") if is_buildkite else ""
+        )
+        log.debug(f"Loading GitHub integration SHA: {sha}")
         event_action = os.getenv('EVENT_ACTION', None)
         if not event_action:
             event_path = os.getenv('GITHUB_EVENT_PATH')
             if event_path and os.path.exists(event_path):
                 with open(event_path, 'r') as f:
                     event = json.load(f)
                     event_action = event.get('action')
+        if not event_action and is_buildkite_pr:
+            # Buildkite provides the current PR state, not the originating
+            # GitHub webhook action. A running PR build is equivalent to the
+            # supported synchronize path for comment updates.
+            event_action = "synchronize"
         repository = os.getenv('GITHUB_REPOSITORY', '')
         owner = os.getenv('GITHUB_REPOSITORY_OWNER', '')
         if '/' in repository:
             owner = repository.split('/')[0]
             repository = repository.split('/')[1]
+        elif is_buildkite:
+            buildkite_owner, buildkite_repository = cls._repository_from_buildkite()
+            owner = owner or buildkite_owner
+            repository = repository or buildkite_repository
 
         default_branch_env = os.getenv('DEFAULT_BRANCH')
         # Consider the variable truthy if it exists and isn't explicitly 'false'
-        is_default = default_branch_env is not None and default_branch_env.lower() != 'false'
+        if default_branch_env is not None:
+            is_default = default_branch_env.lower() != 'false'
+        elif is_buildkite:
+            # Require a branch name: comparing two unset variables would otherwise report
+            # every build as the default branch and overwrite the repository's baseline.
+            buildkite_branch = os.getenv("BUILDKITE_BRANCH")
+            is_default = bool(
+                not is_buildkite_pr
+                and buildkite_branch
+                and buildkite_branch == os.getenv("BUILDKITE_PIPELINE_DEFAULT_BRANCH")
+            )
+        else:
+            is_default = False
+
+        event_name = os.getenv('GITHUB_EVENT_NAME', '')
+        if not event_name and is_buildkite:
+            event_name = "pull_request" if is_buildkite_pr else "push"
         return cls(
-            sha=os.getenv('GITHUB_SHA', ''),
-            api_url=os.getenv('GITHUB_API_URL', ''),
-            ref_type=os.getenv('GITHUB_REF_TYPE', ''),
-            event_name=os.getenv('GITHUB_EVENT_NAME', ''),
-            workspace=os.getenv('GITHUB_WORKSPACE', ''),
+            sha=sha,
+            api_url=os.getenv('GITHUB_API_URL') or (
+                "https://api.github.com" if is_buildkite else ""
+            ),
+            ref_type=os.getenv('GITHUB_REF_TYPE') or (
+                "branch" if is_buildkite else ""
+            ),
+            event_name=event_name,
+            workspace=os.getenv('GITHUB_WORKSPACE') or (
+                os.getenv("BUILDKITE_BUILD_CHECKOUT_PATH", "") if is_buildkite else ""
+            ),
             repository=repository,
-            ref_name=os.getenv('GITHUB_REF_NAME', ''),
+            ref_name=os.getenv('GITHUB_REF_NAME') or (
+                os.getenv("BUILDKITE_BRANCH", "") if is_buildkite else ""
+            ),
             default_branch=is_default,
             is_default_branch=is_default,
             pr_number=pr_number,
             pr_name=os.getenv('PR_NAME'),
-            commit_message=os.getenv('COMMIT_MESSAGE'),
-            actor=os.getenv('GITHUB_ACTOR', ''),
+            commit_message=os.getenv('COMMIT_MESSAGE') or (
+                os.getenv("BUILDKITE_MESSAGE") if is_buildkite else None
+            ),
+            actor=os.getenv('GITHUB_ACTOR') or (
+                os.getenv("BUILDKITE_BUILD_CREATOR", "") if is_buildkite else ""
+            ),
             env=os.getenv('GITHUB_ENV', ''),
             token=token,
             owner=owner,

tests/unit/test_github_buildkite_config.py

@@ -0,0 +1,173 @@
+import pytest
+
+from socketsecurity.core.scm.github import Github, GithubConfig
+
+CONTEXT_VARIABLES = (
+    "BUILDKITE",
+    "BUILDKITE_BRANCH",
+    "BUILDKITE_BUILD_CHECKOUT_PATH",
+    "BUILDKITE_BUILD_CREATOR",
+    "BUILDKITE_COMMIT",
+    "BUILDKITE_MESSAGE",
+    "BUILDKITE_PIPELINE_DEFAULT_BRANCH",
+    "BUILDKITE_PULL_REQUEST",
+    "BUILDKITE_PULL_REQUEST_REPO",
+    "BUILDKITE_REPO",
+    "DEFAULT_BRANCH",
+    "EVENT_ACTION",
+    "GH_API_TOKEN",
+    "GITHUB_ACTOR",
+    "GITHUB_API_URL",
+    "GITHUB_EVENT_NAME",
+    "GITHUB_EVENT_PATH",
+    "GITHUB_REF_NAME",
+    "GITHUB_REF_TYPE",
+    "GITHUB_REPOSITORY",
+    "GITHUB_REPOSITORY_OWNER",
+    "GITHUB_SHA",
+    "GITHUB_WORKSPACE",
+    "PR_NUMBER",
+)
+
+
+@pytest.fixture(autouse=True)
+def clear_context(monkeypatch):
+    for variable in CONTEXT_VARIABLES:
+        monkeypatch.delenv(variable, raising=False)
+    monkeypatch.setenv("GH_API_TOKEN", "test-token")
+
+
+def test_github_config_uses_native_buildkite_pull_request_context(monkeypatch):
+    values = {
+        "BUILDKITE": "true",
+        "BUILDKITE_BRANCH": "feature/socket",
+        "BUILDKITE_BUILD_CHECKOUT_PATH": "/workspace/repo",
+        "BUILDKITE_BUILD_CREATOR": "octocat",
+        "BUILDKITE_COMMIT": "a" * 40,
+        "BUILDKITE_MESSAGE": "Update dependencies",
+        "BUILDKITE_PIPELINE_DEFAULT_BRANCH": "main",
+        "BUILDKITE_PULL_REQUEST": "123",
+        "BUILDKITE_PULL_REQUEST_REPO": "git@github.com:acme/widgets.git",
+        "BUILDKITE_REPO": "git@github.com:acme/widgets.git",
+    }
+    for name, value in values.items():
+        monkeypatch.setenv(name, value)
+
+    config = GithubConfig.from_env()
+
+    assert config.sha == "a" * 40
+    assert config.api_url == "https://api.github.com"
+    assert config.ref_type == "branch"
+    assert config.event_name == "pull_request"
+    assert config.event_action == "synchronize"
+    assert config.workspace == "/workspace/repo"
+    assert config.owner == "acme"
+    assert config.repository == "widgets"
+    assert config.ref_name == "feature/socket"
+    assert config.pr_number == "123"
+    assert config.commit_message == "Update dependencies"
+    assert config.actor == "octocat"
+    assert config.is_default_branch is False
+    assert Github(client=object(), config=config).check_event_type() == "diff"
+
+
+def test_buildkite_non_pr_build_uses_push_and_default_branch(monkeypatch):
+    values = {
+        "BUILDKITE": "true",
+        "BUILDKITE_BRANCH": "main",
+        "BUILDKITE_COMMIT": "b" * 40,
+        "BUILDKITE_PIPELINE_DEFAULT_BRANCH": "main",
+        "BUILDKITE_PULL_REQUEST": "false",
+        "BUILDKITE_REPO": "https://github.com/acme/widgets.git",
+    }
+    for name, value in values.items():
+        monkeypatch.setenv(name, value)
+
+    config = GithubConfig.from_env()
+
+    assert config.event_name == "push"
+    assert config.pr_number is None
+    assert config.owner == "acme"
+    assert config.repository == "widgets"
+    assert config.is_default_branch is True
+    assert Github(client=object(), config=config).check_event_type() == "main"
+
+
+@pytest.mark.parametrize(
+    "branch_variables",
+    [
+        {},
+        {"BUILDKITE_BRANCH": "feature/socket"},
+        {"BUILDKITE_PIPELINE_DEFAULT_BRANCH": "main"},
+    ],
+)
+def test_buildkite_default_branch_requires_a_matching_branch_name(
+        monkeypatch, branch_variables
+):
+    """Absent branch context must not be read as 'this build is the default branch'."""
+    monkeypatch.setenv("BUILDKITE", "true")
+    for name, value in branch_variables.items():
+        monkeypatch.setenv(name, value)
+
+    config = GithubConfig.from_env()
+
+    assert config.is_default_branch is False
+    assert config.default_branch is False
+
+
+def test_explicit_github_values_take_priority_in_buildkite(monkeypatch):
+    values = {
+        "BUILDKITE": "true",
+        "BUILDKITE_BRANCH": "buildkite-branch",
+        "BUILDKITE_COMMIT": "b" * 40,
+        "BUILDKITE_PULL_REQUEST": "123",
+        "BUILDKITE_REPO": "git@github.com:buildkite/repository.git",
+        "EVENT_ACTION": "opened",
+        "GITHUB_API_URL": "https://github.example/api/v3",
+        "GITHUB_EVENT_NAME": "pull_request",
+        "GITHUB_REF_NAME": "github-branch",
+        "GITHUB_REF_TYPE": "branch",
+        "GITHUB_REPOSITORY": "github/repository",
+        "GITHUB_SHA": "c" * 40,
+        "GITHUB_WORKSPACE": "/github/workspace",
+        "PR_NUMBER": "456",
+    }
+    for name, value in values.items():
+        monkeypatch.setenv(name, value)
+
+    config = GithubConfig.from_env()
+
+    assert config.sha == "c" * 40
+    assert config.api_url == "https://github.example/api/v3"
+    assert config.workspace == "/github/workspace"
+    assert config.owner == "github"
+    assert config.repository == "repository"
+    assert config.ref_name == "github-branch"
+    assert config.pr_number == "456"
+    assert config.event_action == "opened"
+
+
+@pytest.mark.parametrize(
+    ("repository_url", "expected"),
+    [
+        ("git@github.com:acme/widgets.git", ("acme", "widgets")),
+        ("https://github.com/acme/widgets.git", ("acme", "widgets")),
+        ("ssh://git@github.com/acme/widgets.git", ("acme", "widgets")),
+        ("", ("", "")),
+        ("not-a-repository", ("", "")),
+    ],
+)
+def test_buildkite_repository_url_parsing(monkeypatch, repository_url, expected):
+    monkeypatch.setenv("BUILDKITE_REPO", repository_url)
+
+    assert GithubConfig._repository_from_buildkite() == expected
+
+
+def test_buildkite_pipeline_repository_wins_over_pull_request_fork(monkeypatch):
+    monkeypatch.setenv("BUILDKITE_REPO", "git@github.com:acme/widgets.git")
+    monkeypatch.setenv(
+        "BUILDKITE_PULL_REQUEST_REPO",
+        "git@github.com:contributor/widgets.git",
+    )
+
+    assert GithubConfig._repository_from_buildkite() == ("acme", "widgets")