Skip to content

configuration.md

Latest commit

 

History

History
186 lines (143 loc) · 6.79 KB

configuration.md

File metadata and controls

186 lines (143 loc) · 6.79 KB
Raw

Configuration

RepoWolf loads one strict YAML configuration at startup. A configuration change requires a service restart.

Policy model

A provider defines its kind, API host, Git host, and token environment name. A repository maps one policy name to an owner, repository name, provider, and Git limits. A principal names one or more token environment variables. A grant gives that principal an explicit capability set for one repository.

Tokens and TLS

Generate a distinct token for each sandbox or project role:

repowolf token generate

The command prints the token once. Store it in a secret manager. Configuration names the environment variable that will hold the token; it never contains the token value or a digest.

For a local deployment, create a private CA and server certificate beneath an existing operator-controlled directory:

install -d -m 0700 /var/lib/repowolf
repowolf cert init --output /var/lib/repowolf/tls --dns repowolf.internal --ip 127.0.0.1

The output path must not already exist. Distribute only the generated CA certificate to clients. Keep CA and server private keys service-side. Production Kubernetes deployments can use cert-manager or another operator-controlled issuer instead.

Service configuration

RepoWolf loads strict YAML once at startup. Unknown or duplicate fields, unsupported schema versions, invalid references, unknown capabilities, and unsafe limits are rejected. Changes to configuration, token environments, certificates, or tool paths require a restart.

apiVersion: repowolf.dev/v1alpha1
listen: "0.0.0.0:8443"

tls:
  certificate: /run/repowolf/tls/tls.crt
  privateKey: /run/repowolf/tls/tls.key

tools:
  gh: null
  ssh: null

providers:
  github-public:
    kind: github
    apiHost: github.com
    gitHost: github.com
    sshUser: git
    tokenEnv: REPOWOLF_TOKEN_GITHUB_PUBLIC

  gitea-lab:
    kind: gitea
    apiHost: gitea.example.com
    gitHost: gitea.example.com
    sshUser: git
    tokenEnv: REPOWOLF_TOKEN_GITEA_LAB
    caFile: /run/repowolf/gitea-ca.pem

repositories:
  example:
    provider: github-public
    owner: example
    name: repository
    git:
      denyRefs:
        - refs/heads/main
      denyDeletes: true
      maxRefUpdates: 16

principals:
  example-agent:
    tokenEnvs:
      - REPOWOLF_TOKEN_EXAMPLE_AGENT
    grants:
      - repository: example
        capabilities:
          - repository:read
          - issues:read
          - issues:write
          - pull_requests:read
          - pull_requests:write
          - actions:read
          - statuses:read
          - git:read
          - git:write

GitHub capability command families

For the exact supported command forms and resource bounds, read the GitHub CLI compatibility reference.

Capability Command families it permits
repository:read gh auth status, gh api user --jq .login, and gh repo view
issues:read gh issue list, gh issue view, and gh label list
issues:write gh issue create, gh issue edit, gh issue comment, gh issue close, gh issue reopen, and gh label create
pull_requests:read gh pr list and gh pr view
pull_requests:write gh pr create, gh pr edit, gh pr comment, gh pr close, gh pr reopen, and gh pr ready
actions:read gh run list and gh run view
statuses:read gh status get and gh pr checks
git:read Git fetch and clone operations through repowolf-git-ssh
git:write Git push operations through repowolf-git-ssh

gh --version is a local command. It does not require a capability.

Gitea repository view

The restricted tea personality supports exactly this repository-view form (with repo as an alias for repos):

tea repos OWNER/REPO --repo OWNER/REPO [--output table|simple|json]

The positional and flagged selectors must identify the same configured Gitea repository, compared with ASCII case-insensitive matching. The command requires exactly the repository:read capability for that repository. Output defaults to simple; all other tea commands, flags, inference paths, prompts, login, help, and version paths are rejected.

Validate policy without loading token values, TLS files, or provider executables:

repowolf config validate --config /etc/repowolf/repowolf.yaml

Set every environment variable named by tokenEnvs and tokenEnv before you start the service. A provider record stores only the token environment name. For this example, export the values in the protected service environment:

export REPOWOLF_TOKEN_GITHUB_PUBLIC='<provider-token>'
export REPOWOLF_TOKEN_GITEA_LAB='<provider-token>'
export REPOWOLF_TOKEN_EXAMPLE_AGENT='<generated-principal-token>'

New GitHub records and all Gitea records require an explicit tokenEnv. An empty or null tokenEnv stops startup. One GitHub record can omit tokenEnv during migration. In that case, startup accepts exactly one non-empty GH_TOKEN or GITHUB_TOKEN. Startup stops if both variables are present, both are absent, or the one present value is empty.

A Gitea provider may set caFile to a non-empty path to a private PEM CA bundle. The file must be readable, regular, contain at least one valid certificate, and be no larger than 1 MiB. These certificates augment the system trust roots rather than replacing them. caFile is rejected for GitHub providers.

Each Gitea API client requires TLS 1.3 with normal API-hostname verification, rejects every redirect, limits a whole operation to two minutes, and limits each decoded response body to 8 MiB. The client is constructed at startup without probing Gitea and is used only by the restricted repository-view RPC. Changes to a provider token, caFile, or CA bundle require a service restart.

SSH configuration belongs only in the service environment and filesystem. A null tool path resolves gh or ssh once from service startup PATH; an absolute YAML path can pin either executable.

Start the service with:

repowolf serve --config /etc/repowolf/repowolf.yaml

Audit JSON Lines are emitted on standard output for collection by the supervisor.

Client configuration

Each sandbox receives only these values:

  • REPOWOLF_ENDPOINT: the service's https:// URL, for example https://repowolf.internal:8443;
  • REPOWOLF_TOKEN: that sandbox role's generated bearer token;
  • REPOWOLF_CA_FILE: a readable PEM public CA certificate, unless the CA is already in the platform trust store;
  • optional REPOWOLF_SERVER_NAME: an explicit TLS server name when it must differ from the endpoint host.

Put the restricted gh and tea personalities first in sandbox PATH and set GIT_SSH_COMMAND=repowolf-git-ssh. Do not put token values in Git remotes, URLs, arguments, repository files, or logs.

After configuration, select a deployment.