theam / theam/facility

Document the repository settings that back the human gates

Open
#48 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
TypeScript
Stars
71
Forks
64
Avg merge
15h 38m
Merged PRs (30d)
66

Description

Facility's core claim is that agents cannot approve their own work, cannot merge, and cannot push to protected branches. Some of that is enforced by Facility; some of it depends on how the GitHub repository is configured, and the documentation does not currently say which is which.

That gap is easy to hit: a repository can run the whole loop, look correct, and still allow an automated actor to satisfy a human gate — for example when Allow GitHub Actions to create and approve pull requests is left enabled, or when the default branch has no protection at all.

Scope

  • A short section — likely in the security reference, linked from the kickstart and existing-repo guides — listing the repository settings a Facility-governed repository should have, and stating for each whether Facility enforces it or the setting does.
  • Cover at least: Actions approving pull requests, default GITHUB_TOKEN permissions, default-branch protection and required checks, and who may merge.
  • facility doctor --github already checks parts of the GitHub side. Where a setting is checkable through the API, say so, and note the ones worth adding to doctor as a follow-up.

Acceptance

  • A reader can tell, per setting, whether skipping it weakens a gate the product advertises.
  • The guides point at it before the first agent run, not after.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the security reference, kickstart guide, existing-repo guide, and the facility doctor --github checks. Document the required GitHub settings, identify which protections Facility enforces versus repository configuration, and link the reference before the first agent run. Note API-checkable gaps as follow-up work for doctor.

Written by the indexing model from the issue text.

Assessment

Tech stack
github, github-actions
Domain
devops, documentation, security
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
70/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.