Repository Owners

The owners of the folders of a repository that manage.py load_from_github loads.

load_from_github applies a repository’s manifests as one user, so that every resource belongs to one account. An organization of several accounts (ADR-036) keeps its resources in the accounts of the departments that own them: its IT department’s Secrets and Connections in IT’s account, its HR assistant in HR’s, and so on. A repository says which by mapping its folders to their owners. The Stackademy project, https://github.com/smarter-sh/stackademy, is the reference.

The scheme

  • The file. owners.yaml, OWNERS_CONFIG, at the repository’s root. Its model is RepositoryOwnersConfig:

    owners:
      - path: departments/it                 # a folder, relative to the repository's root
        username: stackademy_it_admin        # the user who applies, and so owns, its manifests
        accountNumber: "2718-2818-0001"      # the account in which they own them
    
  • Which folder. A manifest belongs to the deepest folder of the file that contains it, so a folder’s owner may be overridden for one of its subfolders. A manifest in no listed folder is applied by load_from_github’s own user, as before.

  • The organization itself. Account and User manifests are always applied by load_from_github’s own user, wherever they are, because they declare the accounts and the people that own the rest, and must exist first.

  • Where it applies. Only when the repository is loaded into the Smarter account, as manage.py initialize_platform loads it: an organization’s resources exist once. Loaded into any other account, e.g. by manage.py initialize_account, which copies a repository’s plugins and LLMClients into a new account, the manifests of owned folders are skipped, because they belong to their owners, not to that account.

  • Failures. An owner who doesn’t exist, or doesn’t belong to the account that the file names, fails each of their manifests, and not the others. A file that is not valid fails load_from_github before anything is applied.

smarter.apps.account.repository_owners.OWNERS_CONFIG = 'owners.yaml'

A repository’s owners file, at its root, RepositoryOwnersConfig.

class smarter.apps.account.repository_owners.RepositoryOwner(**data)[source]

Bases: BaseModel

One folder of owners.yaml, and the user who applies, and so owns, its manifests.

accountNumber: str
model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

path: str
username: str
classmethod validate_account_number(v)[source]

Validate that the account number has the form 1234-5678-9012.

Parameters:

v (str) – The account number.

Return type:

str

Returns:

The account number.

Raises:

ValueError – If it isn’t an account number.

classmethod validate_path(v)[source]

Validate that the path is a folder inside the repository.

Parameters:

v (str) – The path.

Return type:

str

Returns:

The path, normalized, without a trailing separator.

Raises:

ValueError – If it is empty, absolute, the repository’s root, or leaves the repository.

class smarter.apps.account.repository_owners.RepositoryOwnersConfig(**data)[source]

Bases: BaseModel

A repository’s owners.yaml: which user applies the manifests of each of its folders.

See the scheme in smarter.apps.account.repository_owners.

model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

owner_for(path)[source]

Return the owner of the deepest listed folder that contains a file.

Parameters:

path (str) – The file, relative to the repository’s root, e.g. departments/hr/plugins/hr.yaml.

Returns:

Its folder’s owner, or None if no listed folder contains it.

Return type:

RepositoryOwner | None

owners: list[RepositoryOwner]
classmethod validate_unique_paths(v)[source]

Validate that each folder is listed once.

Parameters:

v (list[RepositoryOwner]) – The owners.

Return type:

list[RepositoryOwner]

Returns:

The owners.

Raises:

ValueError – If a folder is listed more than once.

smarter.apps.account.repository_owners.load_owners_config(local_path)[source]

Read and validate a repository’s owners.yaml.

Parameters:

local_path (str) – The repository’s clone.

Returns:

The configuration, or None if the repository has none.

Return type:

RepositoryOwnersConfig | None

Raises:

SmarterValueError – If the file is not valid YAML, or not a valid configuration.

smarter.apps.account.repository_owners.owners_config_path(local_path)[source]

Return the path of a repository’s owners file, whether or not it exists.

Parameters:

local_path (str) – The repository’s clone.

Returns:

<local_path>/owners.yaml.

Return type:

str