feat: validate secret names client-side before API request

Add client-side validation for GitHub secret names in repository and organization secret creation methods to catch invalid names (e.g. starting with digits or "GITHUB_") before triggering API errors.

Author: dclong

github_rest_api/github.py

@@ -6,11 +6,39 @@
 from enum import StrEnum
 from typing import Any, Callable
 from pathlib import Path
+import re
 import requests
 from nacl import encoding, public
 
 URL_API = "https://api.github.com"
 
+_SECRET_NAME_PATTERN = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+
+
+def _validate_secret_name(name: str) -> None:
+    """Validate a secret name against GitHub's naming rules.
+
+    GitHub rejects invalid secret names with a 422 response. Validating the
+    name client-side surfaces a clear error before the request is sent.
+
+    :param name: The name of the secret.
+    :raises ValueError: If the name is empty, starts with the reserved
+        ``GITHUB_`` prefix, starts with a digit, or contains characters other
+        than alphanumerics and underscores.
+    """
+    if not name:
+        raise ValueError("A secret name must not be empty.")
+    if name.upper().startswith("GITHUB_"):
+        raise ValueError(
+            f"Invalid secret name {name!r}: names must not start with the "
+            "reserved 'GITHUB_' prefix."
+        )
+    if not _SECRET_NAME_PATTERN.fullmatch(name):
+        raise ValueError(
+            f"Invalid secret name {name!r}: names may only contain alphanumeric "
+            "characters and underscores, and must not start with a digit."
+        )
+
 
 def _encrypt_secret(public_key: str, value: str) -> str:
     """Encrypt a secret value using a LibSodium sealed box.
@@ -354,6 +382,7 @@ def create_or_update_secret(
             automatically. Fetch it once and reuse it to avoid a redundant
             request when creating or updating multiple secrets.
         """
+        _validate_secret_name(name)
         if public_key is None:
             public_key = self.get_secret_public_key()
         return self._put(
@@ -549,6 +578,7 @@ def create_or_update_secret(
         :param selected_repository_ids: Repository IDs that can access the secret
             when visibility is `selected`.
         """
+        _validate_secret_name(name)
         if selected_repository_ids and visibility != SecretVisibility.SELECTED:
             raise ValueError(
                 "`selected_repository_ids` can only be provided when `visibility` is 'selected'."

tests/test_github.py

@@ -1,7 +1,14 @@
 import os
 from base64 import b64decode
+import pytest
 from nacl import encoding, public
-from github_rest_api.github import User, Organization, Repository, _encrypt_secret
+from github_rest_api.github import (
+    User,
+    Organization,
+    Repository,
+    _encrypt_secret,
+    _validate_secret_name,
+)
 
 TOKEN = os.environ.get("GITHUB_TOKEN", "")
 
@@ -14,6 +21,32 @@ def test_encrypt_secret_roundtrip():
     assert decrypted == b"s3cret-value"
 
 
+@pytest.mark.parametrize(
+    "name",
+    ["MY_SECRET", "_underscore", "Token123", "a"],
+)
+def test_validate_secret_name_valid(name):
+    _validate_secret_name(name)
+
+
+@pytest.mark.parametrize(
+    "name",
+    [
+        "",
+        "GITHUB_ACTIONS",
+        "GITHUB_TOKEN",
+        "github_token",
+        "GitHub_Token",
+        "1SECRET",
+        "MY-SECRET",
+        "MY SECRET",
+    ],
+)
+def test_validate_secret_name_invalid(name):
+    with pytest.raises(ValueError):
+        _validate_secret_name(name)
+
+
 def test_user_get_repositories():
     user = User(TOKEN, "dclong")
     repos = user.get_repositories()