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.

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.

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 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.

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.

Pages

  • Set the Pages source to GitHub Actions.

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

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.

Reporting

Enable private vulnerability reporting and keep SECURITY.md accurate. Project-practice evidence lists what else a public project should be able to show.

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:

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.