ghfleet 0.1.0__py3-none-any.whl

ghfleet/__init__.py

@@ -0,0 +1,47 @@
+"""
+Declare GitHub repositories, secrets, workflow permissions and branch protection
+rulesets from a configuration dictionary.
+
+    from ghfleet import apply, load_config
+
+    apply(load_config("config.yml"))
+
+`apply` takes the configuration as a plain dictionary, so it does not care whether it
+came from YAML, JSON or was built in code. The two conventions it would otherwise
+impose -- where the token of an owner comes from, and where the value of a secret
+comes from -- are its keyword arguments.
+"""
+
+from .config import (
+    BRANCH_PROTECTION_KEYS,
+    DEFAULT_BRANCH_PROTECTION_RULES,
+    REPOSITORY_SETTINGS_KEYS,
+    branch_protection_of,
+    load_config,
+    repositories_of,
+    repository_settings_of,
+    resolve_list_references,
+    ruleset_name_of,
+)
+from .resources import (
+    apply,
+    get_owner_plan,
+    secret_value_from_environment,
+    token_from_environment,
+)
+
+__all__ = [
+    "BRANCH_PROTECTION_KEYS",
+    "DEFAULT_BRANCH_PROTECTION_RULES",
+    "REPOSITORY_SETTINGS_KEYS",
+    "apply",
+    "branch_protection_of",
+    "get_owner_plan",
+    "load_config",
+    "repositories_of",
+    "repository_settings_of",
+    "resolve_list_references",
+    "ruleset_name_of",
+    "secret_value_from_environment",
+    "token_from_environment",
+]

ghfleet/config.py

@@ -0,0 +1,148 @@
+"""Reading and validating the configuration."""
+
+import yaml
+
+# Repository properties this program is able to manage: every one of them is both
+# readable from the `github.get_repository` data source and writable on the
+# `github.Repository` resource. `repository_settings` in config.yml accepts exactly
+# these keys, and whatever it leaves out is fed back from the data source so Pulumi
+# never overwrites it with a provider default.
+#
+# Left out on purpose: `name` (set from the config), `default_branch` (deprecated on
+# the resource, use `BranchDefault`), `private` (superseded by `visibility`), `fork`
+# (a creation-time input), and `has_downloads` (deprecated on the provider, which
+# warns once per repository on every run).
+#
+# `pages` is deliberately absent as well, and that absence is what disables GitHub
+# Pages: the provider calls DisablePages when the property is empty. The documentation
+# is served from Cloudflare (opensource.byjg.com), so no repository here should have a
+# Pages site -- the one exception is the owner's user site, handled in __main__.py.
+# It could not be declared anyway -- the data source returns a list while the resource
+# takes a single object.
+#
+# `allow_forking` is also out. It only configures private forking of *organization*
+# owned private repositories, and even there it depends on an organization-level
+# policy; on a public repository it means nothing. The provider documents the correct
+# use as leaving it unset, and only sends it when the value changes on a non-public
+# repository -- declaring it made GitHub answer 422 on byjg/boletimdeurna, a private
+# repository of a user account, where the setting does not exist at all.
+REPOSITORY_SETTINGS_KEYS = (
+    "allow_auto_merge",
+    "allow_merge_commit",
+    "allow_rebase_merge",
+    "allow_squash_merge",
+    "allow_update_branch",
+    "archived",
+    "delete_branch_on_merge",
+    "description",
+    "has_discussions",
+    "has_issues",
+    "has_projects",
+    "has_wiki",
+    "homepage_url",
+    "is_template",
+    "merge_commit_message",
+    "merge_commit_title",
+    "squash_merge_commit_message",
+    "squash_merge_commit_title",
+    "topics",
+    "visibility",
+)
+
+
+# Keys accepted inside a `branch_protection` block. `rules`, `bypass_actors` and
+# `ref_name` are handed to the provider as they are written, so every rule the
+# provider supports is available from config.yml without any code here knowing it.
+BRANCH_PROTECTION_KEYS = frozenset(
+    {
+        "enabled",
+        "enforcement",
+        "name",
+        "target",
+        "ref_name",
+        "rules",
+        "bypass_actors",
+        "bypass_actor_ids",
+    }
+)
+
+# The policy applied when a `branch_protection` block does not carry its own `rules`.
+# It is a default, not a rule of the program: write `rules` in config.yml to replace it.
+DEFAULT_BRANCH_PROTECTION_RULES = {
+    "pull_request": {
+        "required_approving_review_count": 1,
+        "dismiss_stale_reviews_on_push": True,
+        "require_code_owner_review": False,
+        "require_last_push_approval": False,
+        "required_review_thread_resolution": False,
+        "allowed_merge_methods": ["merge", "squash", "rebase"],
+    },
+    "deletion": True,
+    "non_fast_forward": True,
+    "required_linear_history": False,
+    "required_signatures": False,
+}
+
+
+def load_config(path):
+    """Load a configuration file in the format this package expects."""
+    with open(path) as file:
+        return yaml.load(file, Loader=yaml.FullLoader)
+
+
+def resolve_list_references(list_items, lists_config):
+    """
+    Resolve list references to actual repository names.
+
+    Args:
+        list_items: List that can contain either repository names or list references
+        lists_config: Dictionary of named lists from the config
+
+    Returns:
+        List of actual repository names
+    """
+    resolved = []
+    for item in list_items:
+        # Check if this item is a reference to a named list
+        if item in lists_config:
+            # It's a list reference, expand it
+            resolved.extend(lists_config[item])
+        else:
+            # It's a direct repository name
+            resolved.append(item)
+    return resolved
+
+
+def repositories_of(entry, config):
+    """Every repository name a `repository` entry covers, lists resolved."""
+    resolved_from_lists = resolve_list_references(entry.get("list", []), config.get("lists", {}))
+    return resolved_from_lists + entry.get("repositories", [])
+
+
+def repository_settings_of(entry):
+    """The `repository_settings` block of an entry, rejecting keys GitHub would ignore."""
+    settings = entry.get("repository_settings", {})
+    unknown = sorted(set(settings) - set(REPOSITORY_SETTINGS_KEYS))
+    if unknown:
+        raise Exception(
+            f"Unknown repository_settings in '{entry.get('name', 'unnamed')}': "
+            f"{', '.join(unknown)}. Aborting."
+        )
+    return settings
+
+
+def branch_protection_of(entry):
+    """The `branch_protection` block of an entry, rejecting keys the program ignores."""
+    config = entry.get("branch_protection", {})
+    unknown = sorted(set(config) - BRANCH_PROTECTION_KEYS)
+    if unknown:
+        raise Exception(
+            f"Unknown branch_protection in '{entry.get('name', 'unnamed')}': "
+            f"{', '.join(unknown)}. Aborting."
+        )
+    return config
+
+
+def ruleset_name_of(branch_protection, default_branch):
+    """The ruleset name, which import_rulesets.py has to match to adopt an existing one."""
+    return branch_protection.get("name", f"Protect {default_branch}")

ghfleet/resources.py

@@ -0,0 +1,285 @@
+"""Turning a configuration into Pulumi resources."""
+
+import json
+import os
+import urllib.error
+import urllib.request
+
+import pulumi
+import pulumi_github as github
+
+from .config import (
+    DEFAULT_BRANCH_PROTECTION_RULES,
+    REPOSITORY_SETTINGS_KEYS,
+    branch_protection_of,
+    repositories_of,
+    repository_settings_of,
+    ruleset_name_of,
+)
+
+
+def github_api_get(path, token):
+    """GET a GitHub REST API path and return the parsed JSON, or None on any HTTP error."""
+    request = urllib.request.Request(
+        f"https://api.github.com{path}",
+        headers={
+            "Authorization": f"Bearer {token}",
+            "Accept": "application/vnd.github+json",
+            "X-GitHub-Api-Version": "2022-11-28",
+        },
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=10) as response:
+            return json.load(response)
+    except urllib.error.URLError:
+        return None
+
+
+def get_owner_plan(owner, token):
+    """
+    Return the GitHub plan name for an owner ("free", "pro", "team", ...), or None
+    if it cannot be determined.
+
+    The plan lives in a different place depending on the owner type:
+      - Organization: GET /orgs/{owner}  (token needs the admin:org scope)
+      - User account: GET /user          (token needs the read:user scope)
+    """
+    account = github_api_get(f"/users/{owner}", token)
+    if account is None:
+        return None
+
+    if account.get("type") == "Organization":
+        data = github_api_get(f"/orgs/{owner}", token)
+    else:
+        # /user is the *authenticated* user, which is only the plan we want
+        # when the token actually belongs to this owner.
+        data = github_api_get("/user", token)
+        if data is not None and data.get("login") != owner:
+            return None
+
+    return ((data or {}).get("plan") or {}).get("name")
+
+
+def token_from_environment(owner):
+    """The token for an owner, from GITHUB_ACCESS_TOKEN_<owner>."""
+    variable = f"GITHUB_ACCESS_TOKEN_{owner.replace('-', '_')}"
+    token = os.environ.get(variable)
+    if token is None:
+        raise Exception(f"{variable} is not set. Aborting.")
+    return token
+
+
+def secret_value_from_environment(secret):
+    """Value from the configuration, else from the environment variable named after it."""
+    value = secret.get("value")
+    return value if value is not None else os.environ.get(secret["name"])
+
+
+def apply(config, *, token_for=token_from_environment, secret_value=secret_value_from_environment):
+    """
+    Declare every resource the configuration describes.
+
+    Args:
+        config: The configuration, as `load_config` returns it.
+        token_for: Called with an owner, returns its GitHub token. Defaults to reading
+            GITHUB_ACCESS_TOKEN_<owner> from the environment, raising when it is unset.
+        secret_value: Called with a `secrets` entry, returns the value to write.
+            Defaults to the entry's own `value`, else the environment variable named
+            after the secret.
+    """
+    # Create GitHub providers once per unique owner
+    providers = {}
+    owner_plans = {}
+    for repository in config.get("repository", []):
+        owner = repository["owner"]
+        if owner not in providers:
+            access_token = token_for(owner)
+            providers[owner] = github.Provider(f"github-{owner}", token=access_token, owner=owner)
+            owner_plans[owner] = get_owner_plan(owner, access_token)
+
+    # Build a comprehensive map of all repositories and their configurations
+    # This prevents duplicate resource creation if a repo appears in multiple configs
+    repo_configs = {}  # Key: "owner/repo_name", Value: merged config
+
+    for repository in config.get("repository", []):
+        owner = repository["owner"]
+
+        repo_list = repositories_of(repository, config)
+
+        # Get settings for this configuration
+        workflow_permissions = repository.get("workflow_permissions", {})
+        branch_protection_config = branch_protection_of(repository)
+        secrets_config = repository.get("secrets", [])
+        repository_settings_config = repository_settings_of(repository)
+
+        # Process each repository and merge configs if it appears multiple times
+        for repo_name_item in repo_list:
+            full_name = f"{owner}/{repo_name_item}"
+
+            if full_name not in repo_configs:
+                # First time seeing this repo
+                repo_configs[full_name] = {
+                    "owner": owner,
+                    "repo_name": repo_name_item,
+                    "workflow_permissions": workflow_permissions,
+                    "branch_protection": branch_protection_config,
+                    "secrets": list(secrets_config),  # Copy the list
+                    "repository_settings": dict(repository_settings_config),  # Copy the dict
+                }
+            else:
+                # Repo already seen, merge configurations
+                existing = repo_configs[full_name]
+
+                # Merge workflow permissions (use most permissive)
+                if workflow_permissions:
+                    existing["workflow_permissions"] = workflow_permissions
+
+                # Merge branch protection (enable if any config enables it)
+                if branch_protection_config.get("enabled", False):
+                    existing["branch_protection"] = branch_protection_config
+
+                # Merge repository settings (a later entry wins on the same key)
+                existing["repository_settings"].update(repository_settings_config)
+
+                # Merge secrets (add new ones, avoid duplicates)
+                existing_secret_names = {s["name"] for s in existing["secrets"]}
+                for secret in secrets_config:
+                    if secret["name"] not in existing_secret_names:
+                        existing["secrets"].append(secret)
+
+    # Abort before declaring any secret: one without a value would overwrite the
+    # real secret with an empty string in every repository that declares it.
+    missing_secrets = sorted(
+        {
+            secret["name"]
+            for repo_config in repo_configs.values()
+            for secret in repo_config["secrets"]
+            if not secret_value(secret)
+        }
+    )
+    if missing_secrets:
+        raise Exception(
+            f"Secrets without a value: {', '.join(missing_secrets)}. Load env.txt. Aborting."
+        )
+
+    # Now process each unique repository once with merged configuration
+    for full_name, repo_config in repo_configs.items():
+        owner = repo_config["owner"]
+        repo_name_item = repo_config["repo_name"]
+        workflow_permissions = repo_config["workflow_permissions"]
+        branch_protection_config = repo_config["branch_protection"]
+        secrets_config = repo_config["secrets"]
+        repository_settings = repo_config["repository_settings"]
+
+        provider = providers[owner]
+        resource_prefix = full_name.replace("/", "-").replace("_", "-")
+
+        # 1) Get the repository data source
+        repo_data = github.get_repository(
+            full_name=full_name, opts=pulumi.InvokeOptions(provider=provider)
+        )
+
+        # 2) Repository settings
+        # The provider only exposes these through the whole repository resource. The
+        # repositories already exist, so `import_` adopts each one on the run that first
+        # declares it -- no import script, and a repository added to config.yml later is
+        # adopted the same way. Pulumi skips the import once the resource is in the state.
+        # Every property config.yml does not declare is fed back from the data source: the
+        # desired state then equals reality and `pulumi preview` shows a diff only for what
+        # was actually declared, instead of resetting descriptions and topics to a default.
+        if repository_settings:
+            baseline = {key: getattr(repo_data, key) for key in REPOSITORY_SETTINGS_KEYS}
+            # The absence of `pages` disables GitHub Pages, which is what this program
+            # wants everywhere -- except on the owner's user site, the repository named
+            # <owner>.github.io, where GitHub answers 422 "Deactivating GitHub pages for
+            # this repository is not allowed". That restriction is not in the REST
+            # documentation; it is what the API does.
+            is_user_site = repo_name_item.lower() == f"{owner.lower()}.github.io"
+            github.Repository(
+                f"{resource_prefix}-repository",
+                name=repo_name_item,
+                **{**baseline, **repository_settings},
+                opts=pulumi.ResourceOptions(
+                    provider=provider,
+                    import_=repo_name_item,
+                    ignore_changes=["pages"] if is_user_site else [],
+                    # A repository is never ours to delete: `pulumi destroy` drops it from
+                    # the state and leaves it on GitHub.
+                    retain_on_delete=True,
+                ),
+            )
+
+        # 3) Set workflow permissions
+        if workflow_permissions:
+            default_permission = workflow_permissions.get("default", "read")
+            can_approve_pr = workflow_permissions.get("can_approve_pull_request_reviews", False)
+
+            # Set GITHUB_TOKEN default permissions
+            github.WorkflowRepositoryPermissions(
+                f"{resource_prefix}-workflow-permissions",
+                repository=repo_name_item,
+                default_workflow_permissions=default_permission,
+                can_approve_pull_request_reviews=can_approve_pr,
+                opts=pulumi.ResourceOptions(provider=provider),
+            )
+
+        # 4) Create/Update secrets
+        for secret in secrets_config:
+            secret_name = secret["name"]
+            github.ActionsSecret(
+                f"{resource_prefix}-secret-{secret_name.lower().replace('_', '-')}",
+                repository=repo_name_item,
+                secret_name=secret_name,
+                plaintext_value=secret_value(secret),
+                opts=pulumi.ResourceOptions(provider=provider),
+            )
+
+        # 5) Create/Update branch protection ruleset
+        # Rulesets on *private* repos require a paid plan; GitHub answers 403 on the free
+        # plan. Public repos support them on every plan.
+        owner_plan = owner_plans.get(owner)
+        rulesets_supported = repo_data.visibility != "private" or (
+            owner_plan is not None and owner_plan != "free"
+        )
+
+        if branch_protection_config.get("enabled", False) and not rulesets_supported:
+            if owner_plan is None:
+                reason = (
+                    "could not determine the plan for this owner "
+                    "(the token needs read:user for user accounts, admin:org for organizations)"
+                )
+            else:
+                reason = f"private repository on the '{owner_plan}' plan does not support rulesets"
+            pulumi.log.warn(f"Skipping branch protection ruleset for {full_name}: {reason}")
+        elif branch_protection_config.get("enabled", False):
+            # Get the default branch from the data source
+            default_branch = repo_data.default_branch
+
+            # `rules`, `ref_name` and `bypass_actors` go to the provider exactly as they are
+            # written in config.yml -- the resource accepts plain dictionaries -- so every
+            # rule the provider supports is reachable without this program knowing about it.
+            # `bypass_actor_ids` stays as the shorthand for repository roles:
+            # 2 = Triage, 3 = Write, 4 = Maintain, 5 = Admin.
+            bypass_actors = branch_protection_config.get("bypass_actors")
+            if bypass_actors is None:
+                bypass_actors = [
+                    {"actor_id": actor_id, "actor_type": "RepositoryRole", "bypass_mode": "always"}
+                    for actor_id in branch_protection_config.get("bypass_actor_ids", [5])
+                ]
+
+            github.RepositoryRuleset(
+                f"{resource_prefix}-branch-protection",
+                name=ruleset_name_of(branch_protection_config, default_branch),
+                repository=repo_name_item,
+                target=branch_protection_config.get("target", "branch"),
+                enforcement=branch_protection_config.get("enforcement", "active"),
+                bypass_actors=bypass_actors,
+                conditions={
+                    "ref_name": branch_protection_config.get(
+                        "ref_name",
+                        {"includes": [f"refs/heads/{default_branch}"], "excludes": []},
+                    )
+                },
+                rules=branch_protection_config.get("rules", DEFAULT_BRANCH_PROTECTION_RULES),
+                opts=pulumi.ResourceOptions(provider=provider),
+            )

ghfleet-0.1.0.dist-info/METADATA

@@ -0,0 +1,273 @@
+Metadata-Version: 2.5
+Name: ghfleet
+Version: 0.1.0
+Summary: Declare a fleet of GitHub repositories -- settings, secrets, workflow permissions and branch protection rulesets -- from one configuration file, with Pulumi
+Project-URL: Homepage, https://github.com/byjg/pulumi-github-fleet
+Project-URL: Documentation, https://opensource.byjg.com/docs/devops/pulumi-github-fleet/
+Project-URL: Source, https://github.com/byjg/pulumi-github-fleet
+Author-email: Joao Gilberto Magalhaes <joao@byjg.com.br>
+License: MIT License
+        
+        Copyright (c) 2026 Joao Gilberto Magalhães
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: branch-protection,github,infrastructure-as-code,pulumi,repository-settings
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Version Control :: Git
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.10
+Requires-Dist: pulumi-github<7.0.0,>=6.0.0
+Requires-Dist: pulumi<4.0.0,>=3.0.0
+Requires-Dist: pyyaml>=6.0.0
+Description-Content-Type: text/markdown
+
+---
+sidebar_key: pulumi-github-fleet
+tags: [python, devops]
+---
+
+# ghfleet
+
+[![Build](https://github.com/byjg/pulumi-github-fleet/actions/workflows/build.yml/badge.svg)](https://github.com/byjg/pulumi-github-fleet/actions/workflows/build.yml)
+[![PyPI](https://img.shields.io/pypi/v/ghfleet.svg)](https://pypi.org/project/ghfleet/)
+
+Declare a fleet of GitHub repositories from one configuration file, with Pulumi:
+repository settings, Actions secrets, workflow permissions and branch protection
+rulesets.
+
+It exists because the interesting part of managing dozens of repositories is not the
+API calls, it is answering "which repositories get this, and what is it exactly?" in a
+file you can read, review and diff.
+
+## Install
+
+```bash
+pip install ghfleet     # or: uv add ghfleet
+```
+
+## Use
+
+```python
+import pulumi
+
+from ghfleet import apply, load_config
+
+apply(load_config("config.yml"))
+
+pulumi.export("summary", "GitHub repositories configured successfully")
+```
+
+That is the whole Pulumi program. `apply` takes the configuration as a plain
+dictionary, so it does not care whether it came from YAML, JSON or was built in code.
+
+### The two conventions are yours to change
+
+`apply` would otherwise impose where a token and a secret value come from. Both are
+keyword arguments, with the obvious behaviour as the default:
+
+| Argument | Default |
+|---|---|
+| `token_for(owner)` | reads `GITHUB_ACCESS_TOKEN_<owner>` from the environment, raising when unset |
+| `secret_value(secret)` | the entry's own `value`, else the environment variable named after the secret |
+
+```python
+apply(
+    load_config("config.yml"),
+    token_for=lambda owner: vault.read(f"github/{owner}").token,
+    secret_value=lambda secret: vault.read(secret["name"]).value,
+)
+```
+
+## The configuration
+
+```yaml
+lists:
+  services:
+    - api-gateway
+    - billing
+    - notifications
+
+repository:
+  - name: services
+    owner: acme
+    list:
+      - services
+    repositories:
+      - one-off-repo
+    repository_settings:
+      allow_update_branch: true
+    workflow_permissions:
+      default: write
+      can_approve_pull_request_reviews: false
+    branch_protection:
+      enabled: true
+      bypass_actor_ids: [5]
+    secrets:
+      - name: REGISTRY_USER
+        value: acme
+      - name: REGISTRY_TOKEN
+```
+
+- **`lists`** — named lists of repository names, so a repository set is written once and
+  referenced by several entries.
+- **`repository`** — the entries. Each one names an `owner`, the repositories it covers
+  (through `list`, `repositories`, or both), and what they get. A repository named by
+  more than one entry receives the union.
+
+### `repository_settings`
+
+Declare **only** the settings that must be guaranteed. The accepted keys are in
+`REPOSITORY_SETTINGS_KEYS`; an unknown one aborts the run.
+
+A repository that declares this block becomes a `github.Repository` resource, adopted
+into the state on the first run that declares it — no import step. The resource covers
+the *whole* repository, so everything the block does not declare (description, topics,
+visibility, the other merge options) is read back from the `github.get_repository` data
+source and handed to the resource unchanged. Two consequences:
+
+- `pulumi preview` shows a diff only for the keys you declared, which is what makes it
+  a drift report;
+- an undeclared property is *not* enforced: change the description on GitHub and the
+  next run simply follows it.
+
+The resource is declared with `retain_on_delete`, so neither `pulumi destroy` nor
+removing a line from the configuration deletes a repository. Its secrets and ruleset
+*are* removed — only the repository is retained.
+
+`pages` is not an accepted key, and that absence is meaningful: the provider reads it
+as "no Pages site" and disables Pages on any repository that still has one. The one
+exception is the owner's user site, the repository named `<owner>.github.io`, which is
+recognised by name and left alone (see "GitHub says no", below).
+
+### `branch_protection`
+
+```yaml
+branch_protection:
+  enabled: true
+  enforcement: active          # active | evaluate | disabled
+  bypass_actor_ids: [5]        # 2 = Triage, 3 = Write, 4 = Maintain, 5 = Admin
+  rules:
+    pull_request:
+      required_approving_review_count: 2
+      require_code_owner_review: true
+      allowed_merge_methods: [squash]
+    required_status_checks:
+      strict_required_status_checks_policy: true
+      required_checks:
+        - context: "Build"
+    deletion: true
+    non_fast_forward: true
+```
+
+`rules`, `ref_name` and `bypass_actors` are handed to the provider **exactly as
+written** — the resource accepts plain dictionaries — so every rule
+`github.RepositoryRuleset` supports is reachable from the configuration without this
+package knowing about it. The keys are the provider's, in snake_case.
+
+Left out, `rules` falls back to `DEFAULT_BRANCH_PROTECTION_RULES`: one approving
+review, dismiss stale reviews on push, all three merge methods, no branch deletion and
+no force push. It is a default, not a rule of the package — writing `rules` replaces it
+entirely rather than merging into it.
+
+Other keys: `name` (default `Protect <default branch>`), `target` (`branch` or `tag`),
+`ref_name` (`{includes, excludes}`, default the default branch), and `bypass_actors`
+for anything that is not a repository role. An unknown key aborts the run: on a branch
+protection block, a silent typo means a rule that is not enforced.
+
+Note that rulesets on **private** repositories require a paid plan. On the free plan
+GitHub answers 403, so the ruleset is skipped with a warning instead of failing the
+run.
+
+### `secrets`
+
+```yaml
+secrets:
+  - name: REGISTRY_USER
+    value: acme          # in the file, for values that are not secret
+  - name: REGISTRY_TOKEN # no value: taken from the environment
+```
+
+The run aborts before declaring anything if a secret has no value anywhere. That check
+is not politeness: an empty value would overwrite the real secret with an empty string
+in every repository that declares it.
+
+### Sharing blocks between entries
+
+Entries repeat themselves. Use YAML anchors — a feature of the file format, so nothing
+here has to implement it:
+
+```yaml
+x-defaults:
+  branch_protection: &protected
+    enabled: true
+    bypass_actor_ids: [5]
+
+repository:
+  - name: services
+    branch_protection: *protected
+
+  - name: legacy
+    branch_protection:
+      <<: *protected            # inherit, then override
+      enforcement: "disabled"
+```
+
+Precedence stays local and explicit: a key written next to `<<:` wins.
+
+## GitHub says no
+
+Two settings answer 422 whatever you send, and both cost a failed run to discover.
+
+**`allow_forking` on a private repository of a user account.** The repository-level
+forking policy only exists for private repositories owned by an *organization*, and
+even there an organization owner has to allow forking of private repositories first.
+On a public repository the setting means nothing. It is therefore not among the
+accepted keys, which is also what the provider recommends — its schema says to "leave
+unset for the default behaviour". The restriction is not in the REST reference; it is
+in the [forking policy guide](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-the-forking-policy-for-your-repository).
+
+**Deactivating GitHub Pages on the owner's user site.** The repository named
+`<owner>.github.io` cannot have its Pages site unpublished:
+
+```
+DELETE /repos/<owner>/<owner>.github.io/pages: 422 Deactivating GitHub pages
+for this repository is not allowed
+```
+
+This one is documented nowhere — neither the REST reference nor the "Unpublishing a
+GitHub Pages site" guide mentions it, and that guide draws no distinction between a
+user site and a project site. It is only what the API does, so the package recognises
+the repository by name and keeps `pages` out of its diff.
+
+## What this is not
+
+An ordinary Python package, not a Pulumi component: it declares its resources into the
+stack that calls it, and can only be consumed from Python.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

ghfleet-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+ghfleet/__init__.py,sha256=7BEJL3arKLmnYHqkNo5wDA_dp5YTfDipxPm7ElxnpNQ,1260
+ghfleet/config.py,sha256=uC_HhroQKP5R-s7fWJpMMWr1IgVspPzg-9ZK-FzQoQA,5542
+ghfleet/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ghfleet/resources.py,sha256=nPwL-Y9MDcVyInz40gy9Ce20Qad-PWdvn4s4GmjVXBE,12828
+ghfleet-0.1.0.dist-info/METADATA,sha256=oU7cQOglSVNho7CDg0PBpqmlGPzHNd3jrdQHNHX3GP0,10670
+ghfleet-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+ghfleet-0.1.0.dist-info/licenses/LICENSE,sha256=M-c6Pm-D5Pnem_B_AtqS4zAHtsU6EF6hl8ND18eyP2M,1081
+ghfleet-0.1.0.dist-info/RECORD,,

ghfleet-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

ghfleet-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joao Gilberto Magalhães
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.