pragmatiks-github-provider 0.2.1__tar.gz

pragmatiks_github_provider-0.2.1/PKG-INFO

@@ -0,0 +1,25 @@
+Metadata-Version: 2.3
+Name: pragmatiks-github-provider
+Version: 0.2.1
+Summary: GitHub provider for Pragmatiks
+Author: Pragmatiks
+Author-email: Pragmatiks <team@pragmatiks.io>
+Requires-Dist: pragmatiks-sdk>=0.32.4
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: pynacl>=1.5.0
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# GitHub Provider for Pragmatiks
+
+Manage GitHub repositories, environments, and secrets through declarative resources using the GitHub REST API.
+
+## Resources
+
+- **Repository** - Create and manage GitHub repositories with visibility, features, and branch settings
+- **Environment** - Configure deployment environments on repositories with protection rules
+- **Secret** - Manage repository-level and environment-level secrets with automatic encryption
+
+## Authentication
+
+This provider uses GitHub Personal Access Tokens (classic or fine-grained) for authentication. Generate a token at https://github.com/settings/tokens.

pragmatiks_github_provider-0.2.1/README.md

@@ -0,0 +1,13 @@
+# GitHub Provider for Pragmatiks
+
+Manage GitHub repositories, environments, and secrets through declarative resources using the GitHub REST API.
+
+## Resources
+
+- **Repository** - Create and manage GitHub repositories with visibility, features, and branch settings
+- **Environment** - Configure deployment environments on repositories with protection rules
+- **Secret** - Manage repository-level and environment-level secrets with automatic encryption
+
+## Authentication
+
+This provider uses GitHub Personal Access Tokens (classic or fine-grained) for authentication. Generate a token at https://github.com/settings/tokens.

pragmatiks_github_provider-0.2.1/pyproject.toml

@@ -0,0 +1,56 @@
+[project]
+name = "pragmatiks-github-provider"
+version = "0.2.1"
+description = "GitHub provider for Pragmatiks"
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = [
+    "pragmatiks-sdk>=0.32.4",
+    "httpx>=0.28.0",
+    "pynacl>=1.5.0",
+]
+
+authors = [
+    { name = "Pragmatiks", email = "team@pragmatiks.io" },
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.4.1",
+    "pytest-asyncio>=1.0.0",
+    "pytest-cov>=7.0.0",
+    "pytest-mock>=3.14.0",
+    "respx>=0.22.0",
+    "ty>=0.0.14",
+]
+
+[tool.pragma]
+# Provider metadata - used by the platform for discovery and deployment
+provider = "github"
+package = "github_provider"
+display_name = "GitHub"
+description = "Manage GitHub repositories, environments, and secrets through declarative resources using the GitHub REST API."
+tags = ["github", "repositories", "secrets", "environments", "source-control"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+
+[tool.commitizen]
+name = "cz_conventional_commits"
+version = "0.2.1"
+version_files = ["pyproject.toml:^version"]
+tag_format = "github-v$version"
+update_changelog_on_bump = true
+changelog_file = "CHANGELOG.md"
+
+[tool.ruff]
+extend = "../../pyproject.toml"
+line-length = 120
+
+[tool.uv.build-backend]
+module-name = "github_provider"
+
+[build-system]
+requires = ["uv_build>=0.9.8,<0.10.0"]
+build-backend = "uv_build"

pragmatiks_github_provider-0.2.1/src/github_provider/__init__.py

@@ -0,0 +1,43 @@
+"""GitHub provider for Pragmatiks.
+
+Provides GitHub resources for managing repositories, deployment environments,
+and secrets via the GitHub REST API.
+"""
+
+from pragma_sdk import Provider
+
+from github_provider.resources import (
+    Environment,
+    EnvironmentConfig,
+    EnvironmentOutputs,
+    ProtectionRulesConfig,
+    Repository,
+    RepositoryConfig,
+    RepositoryOutputs,
+    ReviewerConfig,
+    Secret,
+    SecretConfig,
+    SecretOutputs,
+)
+
+
+github = Provider()
+
+github.resource("repository")(Repository)
+github.resource("environment")(Environment)
+github.resource("secret")(Secret)
+
+__all__ = [
+    "github",
+    "Environment",
+    "EnvironmentConfig",
+    "EnvironmentOutputs",
+    "ProtectionRulesConfig",
+    "Repository",
+    "RepositoryConfig",
+    "RepositoryOutputs",
+    "ReviewerConfig",
+    "Secret",
+    "SecretConfig",
+    "SecretOutputs",
+]

pragmatiks_github_provider-0.2.1/src/github_provider/client.py

@@ -0,0 +1,59 @@
+"""GitHub REST API HTTP client."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+
+_BASE_URL = "https://api.github.com"
+
+
+def create_github_client(access_token: str) -> httpx.AsyncClient:
+    """Create an authenticated httpx client for the GitHub REST API.
+
+    Args:
+        access_token: GitHub personal access token (classic or fine-grained).
+
+    Returns:
+        Configured async HTTP client with authorization headers and base URL.
+    """
+    return httpx.AsyncClient(
+        base_url=_BASE_URL,
+        headers={
+            "Authorization": f"Bearer {access_token}",
+            "Accept": "application/vnd.github+json",
+            "X-GitHub-Api-Version": "2022-11-28",
+        },
+        timeout=httpx.Timeout(60.0, connect=10.0),
+    )
+
+
+async def raise_for_status(response: httpx.Response) -> None:
+    """Raise a descriptive error if the response indicates failure.
+
+    Extracts the error message from the GitHub API response body when
+    available, falling back to the raw status code otherwise.
+
+    Args:
+        response: HTTP response to check.
+
+    Raises:
+        httpx.HTTPStatusError: If the response status code indicates an error,
+            with the API error message included.
+    """
+    if response.is_success:
+        return
+
+    try:
+        body: dict[str, Any] = response.json()
+        message = body.get("message") or str(body)
+    except Exception:
+        message = response.text or f"HTTP {response.status_code}"
+
+    raise httpx.HTTPStatusError(
+        message=f"GitHub API error: {message}",
+        request=response.request,
+        response=response,
+    )

pragmatiks_github_provider-0.2.1/src/github_provider/resources/__init__.py

@@ -0,0 +1,37 @@
+"""Resource definitions for GitHub provider.
+
+Import and export your Resource classes here for discovery by the runtime.
+"""
+
+from github_provider.resources.environment import (
+    Environment,
+    EnvironmentConfig,
+    EnvironmentOutputs,
+    ProtectionRulesConfig,
+    ReviewerConfig,
+)
+from github_provider.resources.repository import (
+    Repository,
+    RepositoryConfig,
+    RepositoryOutputs,
+)
+from github_provider.resources.secret import (
+    Secret,
+    SecretConfig,
+    SecretOutputs,
+)
+
+
+__all__ = [
+    "Environment",
+    "EnvironmentConfig",
+    "EnvironmentOutputs",
+    "ProtectionRulesConfig",
+    "Repository",
+    "RepositoryConfig",
+    "RepositoryOutputs",
+    "ReviewerConfig",
+    "Secret",
+    "SecretConfig",
+    "SecretOutputs",
+]

pragmatiks_github_provider-0.2.1/src/github_provider/resources/environment.py

@@ -0,0 +1,235 @@
+"""GitHub Environment resource."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pragma_sdk import Config, Field, ImmutableField, Outputs, Resource, SensitiveField
+from pydantic import BaseModel
+from pydantic import Field as PydanticField
+
+from github_provider.client import create_github_client, raise_for_status
+
+
+class ReviewerConfig(BaseModel):
+    """Configuration for an environment protection rule reviewer.
+
+    Attributes:
+        reviewer_type: Type of reviewer (``User`` or ``Team``).
+        reviewer_id: GitHub ID of the user or team.
+    """
+
+    model_config = {"extra": "forbid"}
+
+    reviewer_type: str = "User"
+    reviewer_id: int = 0
+
+
+class ProtectionRulesConfig(BaseModel):
+    """Configuration for environment protection rules.
+
+    Attributes:
+        wait_timer: Number of minutes to wait before allowing deployments
+            (0 to 43200). Set to 0 to disable the wait timer.
+        reviewers: List of required reviewers for deployments.
+    """
+
+    model_config = {"extra": "forbid"}
+
+    wait_timer: int = 0
+    reviewers: list[ReviewerConfig] = PydanticField(default_factory=list)
+
+
+class EnvironmentConfig(Config):
+    """Configuration for a GitHub deployment environment.
+
+    Attributes:
+        access_token: GitHub personal access token for authentication.
+        owner: GitHub user or organization that owns the repository.
+        repository: Repository name where the environment is created.
+        environment_name: Name of the deployment environment
+            (e.g., ``production``, ``staging``).
+        protection_rules: Optional protection rules for the environment.
+    """
+
+    access_token: SensitiveField[str]
+    owner: ImmutableField[str]
+    repository: ImmutableField[str]
+    environment_name: ImmutableField[str]
+    protection_rules: Field[ProtectionRulesConfig] | None = None
+
+
+class EnvironmentOutputs(Outputs):
+    """Outputs from GitHub environment creation.
+
+    Attributes:
+        environment_id: Numeric environment ID assigned by GitHub.
+        environment_name: Name of the deployment environment.
+        html_url: URL to the environment settings page on GitHub.
+        wait_timer: Configured wait timer in minutes (0 if not set).
+        reviewers_count: Number of required reviewers.
+    """
+
+    environment_id: int
+    environment_name: str
+    html_url: str
+    wait_timer: int
+    reviewers_count: int
+
+
+def _build_create_body(config: EnvironmentConfig) -> dict[str, Any]:
+    """Build the API request body for environment creation or update.
+
+    Args:
+        config: Environment configuration.
+
+    Returns:
+        Dictionary suitable for PUT /repos/{owner}/{repo}/environments/{env}.
+    """
+    body: dict[str, Any] = {}
+
+    if config.protection_rules is not None:
+        body["wait_timer"] = config.protection_rules.wait_timer
+
+        if config.protection_rules.reviewers:
+            body["reviewers"] = [
+                {"type": reviewer.reviewer_type, "id": reviewer.reviewer_id}
+                for reviewer in config.protection_rules.reviewers
+            ]
+
+    return body
+
+
+def _build_outputs(data: dict[str, Any], owner: str, repository: str) -> EnvironmentOutputs:
+    """Build outputs from GitHub environment API response data.
+
+    Args:
+        data: Raw environment data from the GitHub API.
+        owner: Repository owner.
+        repository: Repository name.
+
+    Returns:
+        EnvironmentOutputs with environment metadata.
+    """
+    protection_rules = data.get("protection_rules", [])
+    wait_timer = 0
+    reviewers_count = 0
+
+    for rule in protection_rules:
+        if rule.get("type") == "wait_timer":
+            wait_timer = rule.get("wait_timer", 0)
+        elif rule.get("type") == "required_reviewers":
+            reviewers = rule.get("reviewers", [])
+            reviewers_count = len(reviewers)
+
+    return EnvironmentOutputs(
+        environment_id=data["id"],
+        environment_name=data["name"],
+        html_url=f"https://github.com/{owner}/{repository}/settings/environments/{data['id']}",
+        wait_timer=wait_timer,
+        reviewers_count=reviewers_count,
+    )
+
+
+class Environment(Resource[EnvironmentConfig, EnvironmentOutputs]):
+    """GitHub deployment environment resource.
+
+    Creates and manages deployment environments on GitHub repositories
+    via the REST API. Environments can have protection rules such as
+    wait timers and required reviewers.
+
+    Lifecycle:
+        - on_create: Creates or updates an environment using PUT (the
+          GitHub API uses PUT for both create and update). Idempotent.
+        - on_update: Updates the environment configuration by re-applying
+          the PUT request with the new settings.
+        - on_delete: Deletes the environment. Idempotent -- succeeds if
+          the environment does not exist.
+
+    Example::
+
+        resources:
+          - name: production-env
+            provider: github
+            type: environment
+            config:
+              access_token:
+                provider: pragma
+                resource: secret
+                name: github-token
+                field: outputs.value
+              owner: my-org
+              repository: my-repo
+              environment_name: production
+              protection_rules:
+                wait_timer: 30
+                reviewers:
+                  - reviewer_type: User
+                    reviewer_id: 12345
+    """
+
+    async def _apply_environment(self) -> EnvironmentOutputs:
+        """Create or update the environment and return outputs.
+
+        Returns:
+            EnvironmentOutputs with environment details.
+        """
+        client = create_github_client(self.config.access_token)
+
+        try:
+            body = _build_create_body(self.config)
+            response = await client.put(
+                f"/repos/{self.config.owner}/{self.config.repository}/environments/{self.config.environment_name}",
+                json=body,
+            )
+            await raise_for_status(response)
+
+            return _build_outputs(response.json(), self.config.owner, self.config.repository)
+        finally:
+            await client.aclose()
+
+    async def on_create(self) -> EnvironmentOutputs:
+        """Create a deployment environment on the repository.
+
+        Returns:
+            EnvironmentOutputs with environment details.
+        """
+        return await self._apply_environment()
+
+    async def on_update(self, previous_config: EnvironmentConfig) -> EnvironmentOutputs:
+        """Update the environment configuration.
+
+        Args:
+            previous_config: The previous configuration before update.
+
+        Returns:
+            EnvironmentOutputs with updated environment details.
+        """
+        return await self._apply_environment()
+
+    async def on_delete(self) -> None:
+        """Delete the deployment environment.
+
+        Idempotent: Succeeds if the environment does not exist.
+        """
+        client = create_github_client(self.config.access_token)
+
+        try:
+            response = await client.delete(
+                f"/repos/{self.config.owner}/{self.config.repository}/environments/{self.config.environment_name}",
+            )
+
+            if response.status_code == 404:
+                return
+
+            await raise_for_status(response)
+        finally:
+            await client.aclose()
+
+    @classmethod
+    def upgrade(cls, config: dict, outputs: dict) -> tuple[dict, dict]:  # noqa: D102
+        return config, outputs
+
+    @classmethod
+    def downgrade(cls, config: dict, outputs: dict) -> tuple[dict, dict]:  # noqa: D102
+        return config, outputs

pragmatiks_github_provider-0.2.1/src/github_provider/resources/repository.py

@@ -0,0 +1,257 @@
+"""GitHub Repository resource."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pragma_sdk import Config, Field, ImmutableField, Outputs, Resource, SensitiveField
+
+from github_provider.client import create_github_client, raise_for_status
+
+
+class RepositoryConfig(Config):
+    """Configuration for a GitHub repository.
+
+    Attributes:
+        access_token: GitHub personal access token for authentication.
+            Use a pragma/secret resource with a FieldReference to provide this.
+        owner: GitHub user or organization that owns the repository.
+        name: Repository name. Must be unique within the owner's account.
+        description: Short description of the repository.
+        visibility: Repository visibility (``public`` or ``private``).
+        default_branch: Default branch name. Only applied on creation
+            when ``auto_init`` is True.
+        has_issues: Whether to enable the Issues feature.
+        has_wiki: Whether to enable the Wiki feature.
+        has_projects: Whether to enable the Projects feature.
+        auto_init: Whether to initialize the repository with a README.
+            Only used on creation.
+        delete_branch_on_merge: Whether to automatically delete head
+            branches after pull requests are merged.
+        allow_squash_merge: Whether to allow squash-merging pull requests.
+        allow_merge_commit: Whether to allow merging pull requests with a merge commit.
+        allow_rebase_merge: Whether to allow rebase-merging pull requests.
+    """
+
+    access_token: SensitiveField[str]
+    owner: ImmutableField[str]
+    name: ImmutableField[str]
+    description: Field[str] = ""
+    visibility: Field[str] = "private"
+    default_branch: Field[str] = "main"
+    has_issues: Field[bool] = True
+    has_wiki: Field[bool] = False
+    has_projects: Field[bool] = False
+    auto_init: Field[bool] = True
+    delete_branch_on_merge: Field[bool] = True
+    allow_squash_merge: Field[bool] = True
+    allow_merge_commit: Field[bool] = True
+    allow_rebase_merge: Field[bool] = True
+
+
+class RepositoryOutputs(Outputs):
+    """Outputs from GitHub repository creation.
+
+    Attributes:
+        repository_id: Numeric repository ID assigned by GitHub.
+        full_name: Full repository name in ``owner/repo`` format.
+        html_url: URL to the repository on GitHub.
+        clone_url: HTTPS clone URL.
+        ssh_url: SSH clone URL.
+        default_branch: Default branch name.
+        visibility: Repository visibility.
+    """
+
+    repository_id: int
+    full_name: str
+    html_url: str
+    clone_url: str
+    ssh_url: str
+    default_branch: str
+    visibility: str
+
+
+def _build_create_body(config: RepositoryConfig) -> dict[str, Any]:
+    """Build the API request body for repository creation.
+
+    Args:
+        config: Repository configuration.
+
+    Returns:
+        Dictionary suitable for POST /orgs/{org}/repos or POST /user/repos.
+    """
+    return {
+        "name": config.name,
+        "description": config.description,
+        "private": config.visibility == "private",
+        "auto_init": config.auto_init,
+        "has_issues": config.has_issues,
+        "has_wiki": config.has_wiki,
+        "has_projects": config.has_projects,
+        "delete_branch_on_merge": config.delete_branch_on_merge,
+        "allow_squash_merge": config.allow_squash_merge,
+        "allow_merge_commit": config.allow_merge_commit,
+        "allow_rebase_merge": config.allow_rebase_merge,
+    }
+
+
+def _build_update_body(config: RepositoryConfig) -> dict[str, Any]:
+    """Build the API request body for repository update.
+
+    Only includes mutable fields. Owner and name are immutable.
+
+    Args:
+        config: Current repository configuration.
+
+    Returns:
+        Dictionary suitable for PATCH /repos/{owner}/{repo}.
+    """
+    return {
+        "description": config.description,
+        "private": config.visibility == "private",
+        "has_issues": config.has_issues,
+        "has_wiki": config.has_wiki,
+        "has_projects": config.has_projects,
+        "delete_branch_on_merge": config.delete_branch_on_merge,
+        "allow_squash_merge": config.allow_squash_merge,
+        "allow_merge_commit": config.allow_merge_commit,
+        "allow_rebase_merge": config.allow_rebase_merge,
+    }
+
+
+def _build_outputs(data: dict[str, Any]) -> RepositoryOutputs:
+    """Build outputs from GitHub repository API response data.
+
+    Args:
+        data: Raw repository data from the GitHub API.
+
+    Returns:
+        RepositoryOutputs with repository metadata.
+    """
+    return RepositoryOutputs(
+        repository_id=data["id"],
+        full_name=data["full_name"],
+        html_url=data["html_url"],
+        clone_url=data["clone_url"],
+        ssh_url=data["ssh_url"],
+        default_branch=data.get("default_branch", "main"),
+        visibility=data.get("visibility", "private"),
+    )
+
+
+class Repository(Resource[RepositoryConfig, RepositoryOutputs]):
+    """GitHub repository resource.
+
+    Creates and manages GitHub repositories via the REST API. Repositories
+    are created under the specified owner (user or organization) and can
+    be configured with visibility, features, and merge settings.
+
+    Lifecycle:
+        - on_create: Creates a new repository. Uses the organization endpoint
+          when the owner is an organization, or the user endpoint otherwise.
+          Not idempotent -- duplicate calls create duplicate repositories.
+        - on_update: Updates mutable repository settings (description,
+          visibility, features, merge options). Owner and name are immutable.
+        - on_delete: Deletes the repository. Idempotent -- succeeds if the
+          repository does not exist.
+
+    Example::
+
+        resources:
+          - name: my-repo
+            provider: github
+            type: repository
+            config:
+              access_token:
+                provider: pragma
+                resource: secret
+                name: github-token
+                field: outputs.value
+              owner: my-org
+              name: my-repo
+              description: My application repository
+              visibility: private
+              auto_init: true
+              has_issues: true
+              has_wiki: false
+    """
+
+    async def on_create(self) -> RepositoryOutputs:
+        """Create a GitHub repository.
+
+        Returns:
+            RepositoryOutputs with repository details.
+        """
+        client = create_github_client(self.config.access_token)
+
+        try:
+            body = _build_create_body(self.config)
+
+            response = await client.post(f"/orgs/{self.config.owner}/repos", json=body)
+
+            if response.status_code == 404:
+                response = await client.post("/user/repos", json=body)
+
+            await raise_for_status(response)
+
+            return _build_outputs(response.json())
+        finally:
+            await client.aclose()
+
+    async def on_update(self, previous_config: RepositoryConfig) -> RepositoryOutputs:
+        """Update the repository settings if changed.
+
+        Args:
+            previous_config: The previous configuration before update.
+
+        Returns:
+            RepositoryOutputs with current repository state.
+
+        Raises:
+            RuntimeError: If no existing outputs are available for the repository.
+        """
+        if self.outputs is None:
+            msg = "Cannot update repository without existing outputs"
+            raise RuntimeError(msg)
+
+        client = create_github_client(self.config.access_token)
+
+        try:
+            update_body = _build_update_body(self.config)
+            response = await client.patch(
+                f"/repos/{self.config.owner}/{self.config.name}",
+                json=update_body,
+            )
+            await raise_for_status(response)
+
+            return _build_outputs(response.json())
+        finally:
+            await client.aclose()
+
+    async def on_delete(self) -> None:
+        """Delete the GitHub repository.
+
+        Idempotent: Succeeds if the repository does not exist.
+        """
+        if self.outputs is None:
+            return
+
+        client = create_github_client(self.config.access_token)
+
+        try:
+            response = await client.delete(f"/repos/{self.config.owner}/{self.config.name}")
+
+            if response.status_code == 404:
+                return
+
+            await raise_for_status(response)
+        finally:
+            await client.aclose()
+
+    @classmethod
+    def upgrade(cls, config: dict, outputs: dict) -> tuple[dict, dict]:  # noqa: D102
+        return config, outputs
+
+    @classmethod
+    def downgrade(cls, config: dict, outputs: dict) -> tuple[dict, dict]:  # noqa: D102
+        return config, outputs

pragmatiks_github_provider-0.2.1/src/github_provider/resources/secret.py

@@ -0,0 +1,317 @@
+"""GitHub Secret resource."""
+
+from __future__ import annotations
+
+import base64
+from typing import Any
+
+from nacl.encoding import Base64Encoder
+from nacl.public import PublicKey, SealedBox
+from pragma_sdk import Config, Field, ImmutableField, Outputs, Resource, SensitiveField
+
+from github_provider.client import create_github_client, raise_for_status
+
+
+class SecretConfig(Config):
+    """Configuration for a GitHub secret.
+
+    Secrets can be scoped to a repository or to a specific deployment
+    environment within a repository. When ``environment_name`` is set,
+    the secret is created as an environment secret.
+
+    Attributes:
+        access_token: GitHub personal access token for authentication.
+        owner: GitHub user or organization that owns the repository.
+        repository: Repository name.
+        secret_name: Name of the secret. Must match the pattern
+            ``[A-Z_][A-Z0-9_]*``.
+        secret_value: Plaintext secret value. Encrypted automatically
+            before upload using the repository or environment public key.
+        environment_name: Optional deployment environment name. When set,
+            the secret is scoped to this environment instead of the repository.
+    """
+
+    access_token: SensitiveField[str]
+    owner: ImmutableField[str]
+    repository: ImmutableField[str]
+    secret_name: ImmutableField[str]
+    secret_value: SensitiveField[str]
+    environment_name: Field[str] | None = None
+
+
+class SecretOutputs(Outputs):
+    """Outputs from GitHub secret creation.
+
+    Attributes:
+        secret_name: Name of the secret.
+        scope: Scope of the secret (``repository`` or ``environment``).
+        environment_name: Environment name if this is an environment secret,
+            empty string otherwise.
+        created_at: ISO 8601 timestamp of when the secret was created.
+        updated_at: ISO 8601 timestamp of when the secret was last updated.
+    """
+
+    secret_name: str
+    scope: str
+    environment_name: str
+    created_at: str
+    updated_at: str
+
+
+def _encrypt_secret(public_key_b64: str, secret_value: str) -> str:
+    """Encrypt a secret value using the repository's NaCl public key.
+
+    Args:
+        public_key_b64: Base64-encoded public key from the GitHub API.
+        secret_value: Plaintext secret value to encrypt.
+
+    Returns:
+        Base64-encoded encrypted secret value.
+    """
+    public_key_bytes = base64.b64decode(public_key_b64)
+    public_key = PublicKey(public_key_bytes)
+    sealed_box = SealedBox(public_key)
+    encrypted = sealed_box.encrypt(secret_value.encode(), encoder=Base64Encoder)
+
+    return encrypted.decode("utf-8")
+
+
+class Secret(Resource[SecretConfig, SecretOutputs]):
+    """GitHub secret resource.
+
+    Creates and manages secrets on GitHub repositories or deployment
+    environments via the REST API. Secrets are encrypted using the
+    repository or environment public key (NaCl sealed box) before upload.
+
+    GitHub secrets cannot be read back after creation -- only the
+    metadata (name, creation time, update time) is available.
+
+    Lifecycle:
+        - on_create: Fetches the public key, encrypts the secret value,
+          and creates or replaces the secret. Idempotent -- creating an
+          existing secret replaces its value.
+        - on_update: Re-encrypts and replaces the secret value using PUT.
+          Same operation as create.
+        - on_delete: Deletes the secret. Idempotent -- succeeds if the
+          secret does not exist.
+
+    Example::
+
+        resources:
+          - name: deploy-key
+            provider: github
+            type: secret
+            config:
+              access_token:
+                provider: pragma
+                resource: secret
+                name: github-token
+                field: outputs.value
+              owner: my-org
+              repository: my-repo
+              secret_name: DEPLOY_KEY
+              secret_value:
+                provider: pragma
+                resource: secret
+                name: deploy-key
+                field: outputs.value
+
+          - name: env-secret
+            provider: github
+            type: secret
+            config:
+              access_token:
+                provider: pragma
+                resource: secret
+                name: github-token
+                field: outputs.value
+              owner: my-org
+              repository: my-repo
+              secret_name: API_KEY
+              secret_value:
+                provider: pragma
+                resource: secret
+                name: api-key
+                field: outputs.value
+              environment_name: production
+    """
+
+    def _is_environment_secret(self) -> bool:
+        """Check whether this secret is scoped to an environment.
+
+        Returns:
+            True if environment_name is set.
+        """
+        return self.config.environment_name is not None
+
+    async def _fetch_public_key(self, client: Any) -> tuple[str, str]:
+        """Fetch the public key for secret encryption.
+
+        Uses the environment public key endpoint when the secret is
+        environment-scoped, otherwise uses the repository endpoint.
+
+        Args:
+            client: Authenticated GitHub API client.
+
+        Returns:
+            Tuple of (key_b64, key_id).
+        """
+        if self._is_environment_secret():
+            response = await client.get(
+                f"/repos/{self.config.owner}/{self.config.repository}"
+                f"/environments/{self.config.environment_name}/secrets/public-key",
+            )
+        else:
+            response = await client.get(
+                f"/repos/{self.config.owner}/{self.config.repository}/actions/secrets/public-key",
+            )
+
+        await raise_for_status(response)
+        data = response.json()
+
+        return data["key"], data["key_id"]
+
+    async def _put_secret(self, client: Any, encrypted_value: str, key_id: str) -> None:
+        """Create or replace the secret with the encrypted value.
+
+        Args:
+            client: Authenticated GitHub API client.
+            encrypted_value: Base64-encoded encrypted secret value.
+            key_id: Public key ID used for encryption.
+        """
+        body = {
+            "encrypted_value": encrypted_value,
+            "key_id": key_id,
+        }
+
+        if self._is_environment_secret():
+            response = await client.put(
+                f"/repos/{self.config.owner}/{self.config.repository}"
+                f"/environments/{self.config.environment_name}/secrets/{self.config.secret_name}",
+                json=body,
+            )
+        else:
+            response = await client.put(
+                f"/repos/{self.config.owner}/{self.config.repository}/actions/secrets/{self.config.secret_name}",
+                json=body,
+            )
+
+        await raise_for_status(response)
+
+    async def _fetch_secret_metadata(self, client: Any) -> dict[str, Any]:
+        """Fetch secret metadata (name, timestamps).
+
+        Args:
+            client: Authenticated GitHub API client.
+
+        Returns:
+            Secret metadata dictionary from the API.
+        """
+        if self._is_environment_secret():
+            response = await client.get(
+                f"/repos/{self.config.owner}/{self.config.repository}"
+                f"/environments/{self.config.environment_name}/secrets/{self.config.secret_name}",
+            )
+        else:
+            response = await client.get(
+                f"/repos/{self.config.owner}/{self.config.repository}/actions/secrets/{self.config.secret_name}",
+            )
+
+        await raise_for_status(response)
+
+        return response.json()
+
+    def _build_outputs(self, metadata: dict[str, Any]) -> SecretOutputs:
+        """Build outputs from secret metadata.
+
+        Args:
+            metadata: Secret metadata from the GitHub API.
+
+        Returns:
+            SecretOutputs with secret metadata.
+        """
+        scope = "environment" if self._is_environment_secret() else "repository"
+
+        return SecretOutputs(
+            secret_name=metadata["name"],
+            scope=scope,
+            environment_name=self.config.environment_name or "",
+            created_at=metadata.get("created_at", ""),
+            updated_at=metadata.get("updated_at", ""),
+        )
+
+    async def _apply_secret(self) -> SecretOutputs:
+        """Encrypt and create or replace the secret.
+
+        Returns:
+            SecretOutputs with secret metadata.
+        """
+        client = create_github_client(self.config.access_token)
+
+        try:
+            key_b64, key_id = await self._fetch_public_key(client)
+            encrypted_value = _encrypt_secret(key_b64, self.config.secret_value)
+            await self._put_secret(client, encrypted_value, key_id)
+            metadata = await self._fetch_secret_metadata(client)
+
+            return self._build_outputs(metadata)
+        finally:
+            await client.aclose()
+
+    async def on_create(self) -> SecretOutputs:
+        """Create or replace a GitHub secret.
+
+        Returns:
+            SecretOutputs with secret metadata.
+        """
+        return await self._apply_secret()
+
+    async def on_update(self, previous_config: SecretConfig) -> SecretOutputs:
+        """Update the secret value.
+
+        Secrets are replaced entirely on every update since the value
+        cannot be read back for comparison.
+
+        Args:
+            previous_config: The previous configuration before update.
+
+        Returns:
+            SecretOutputs with updated secret metadata.
+        """
+        return await self._apply_secret()
+
+    async def on_delete(self) -> None:
+        """Delete the GitHub secret.
+
+        Idempotent: Succeeds if the secret does not exist.
+        """
+        if self.outputs is None:
+            return
+
+        client = create_github_client(self.config.access_token)
+
+        try:
+            if self._is_environment_secret():
+                response = await client.delete(
+                    f"/repos/{self.config.owner}/{self.config.repository}"
+                    f"/environments/{self.config.environment_name}/secrets/{self.config.secret_name}",
+                )
+            else:
+                response = await client.delete(
+                    f"/repos/{self.config.owner}/{self.config.repository}/actions/secrets/{self.config.secret_name}",
+                )
+
+            if response.status_code == 404:
+                return
+
+            await raise_for_status(response)
+        finally:
+            await client.aclose()
+
+    @classmethod
+    def upgrade(cls, config: dict, outputs: dict) -> tuple[dict, dict]:  # noqa: D102
+        return config, outputs
+
+    @classmethod
+    def downgrade(cls, config: dict, outputs: dict) -> tuple[dict, dict]:  # noqa: D102
+        return config, outputs