> Documentation version: 3. [HTML page](settings.html)

<a id="repository-settings"></a>

# Repository settings

Workflow files do not enforce a process by themselves. The settings in this
chapter are part of the model, and a repository has not adopted it until they
are in place and have been exercised with a real pull request.

<a id="risk-settings-enforcement"></a>

## Risks and controls for settings enforcement

A workflow file can describe a gate that repository settings do not enforce,
or a required check name can refer to no actual job. Verify effective settings
and exercise the boundary. The read-only settings checker reports hidden answers
as unknown and identifies mismatches; a real PR with a deliberately failing
check confirms whether merging is blocked. Check release and Pages environment
restrictions separately. An API configuration report does not establish that a
reporting channel works, a reviewer acted, or a required test covers the right
behavior.

<a id="actions"></a>

## Actions

- Set the default workflow token to read-only. Each job that needs to write
  states its own permission.

- If the repository restricts which actions may run, allow each shared action at
  its reviewed full SHA. An allowlist entry without ` @... ` does not match an
  action reference.

- Do not enable "Allow GitHub Actions to create and approve pull requests". No
  workflow in this model opens a pull request.

<a id="branch-rules"></a>

## Branch rules

Protect the default branch with a ruleset:

- Require a pull request.


- Require status checks to pass on the current commit, with the branch up to
  date. Name the aggregate job of ` ci.yml `, or its one job in a
  [Roc package](overview.md#a-pure-roc-package), and the build job
  of the ` release.yml ` dry run.

- Require signed commits.


- Grant no bypass to any bot: neither an app nor a deploy key is on the
  ruleset’s bypass list.

Verify the rules with a real pull request: a failing check must block the merge,
and a check name that no job produces must be noticed before it is relied on. If
a required name identifies both a check run and a commit status, GitHub requires
both.

Platform repositories that publish linker inputs allow merge commits. The
publisher binds its evidence to exact commit SHAs, and a squash would replace
them; see
[Preserve reviewed history and authority](platforms.md#preserve-reviewed-history-and-authority).

<a id="releases"></a>

## Releases

- Enable immutable releases.


- Create a ` release ` environment restricted to the default branch, with a
  required reviewer where the project has more than one maintainer. The publish
  job of ` release.yml ` names it. Restrict it by name: choose "Selected branches
  and tags" and add the default branch alone. "Protected branches only" is
  wider, because it admits every branch a ruleset later covers.

- Protect tags with a ruleset that targets all tags and restricts updates and
  deletions, so that an existing version tag cannot be moved or deleted.

<a id="pages"></a>

## Pages

- Set the Pages source to GitHub Actions.


- Restrict the ` github-pages ` environment to the default branch, by name as for
  ` release `.

<a id="dependencies"></a>

## Dependencies

Keep a weekly ` github-actions ` entry in Dependabot. Shared actions are pinned by
full SHA, and Dependabot proposes each new one as a pull request. Review it like
any other dependency update, and never replace a full SHA with a branch or tag.

<a id="reporting"></a>

## Reporting

Enable private vulnerability reporting and keep ` SECURITY.md ` accurate.

<a id="confirm-the-settings"></a>

## Confirm the settings

The ` check-settings ` task of roc-automation reads a repository’s settings from
GitHub and reports each line of this chapter as passing or failing. Run it from
a checkout of roc-automation and name the repository:

``` sh
blueprint run check-settings -- <owner>/<name>
```

Three answers only a maintainer can give are flags:

- **` --platform `**: The repository publishes linker inputs. The report notes whether
  merge commits are allowed.

- **` --reviewer-required `**: The project has more than one maintainer. The ` release `
  environment must have a required reviewer.

- **` --no-site `**: The repository publishes no site. The Pages lines are left out.


Each failing line is followed by its fix: the settings page to change, or the
` gh api ` command that changes it. A setting that GitHub would not show is
reported as unknown, never as passing. The task exits with an error while any
line fails or is unknown.

- It only reads. Every request it makes is a ` GET `. Applying a setting stays a
  maintainer’s decision, made on the settings page or by running the printed
  command.

- It uses the maintainer’s own ` gh ` login, which must be able to administer the
  repository. GitHub shows a ruleset’s bypass list and the Actions
  permissions to nobody else. A workflow’s token cannot be granted that access,
  so the task runs on a maintainer’s machine and not in CI.

- It shows that the rules exist, not that they are enforced. A real pull
  request with a failing check is still what shows that the merge is blocked.

- It compares the required check names with the jobs that ran on the pull
  request behind the latest commit on the default branch. It cannot tell
  whether those are the right jobs to require.

- It confirms that ` SECURITY.md ` exists, not that it is accurate.