From d6648226d537ac95514a9b08fe36e3d28198e152 Mon Sep 17 00:00:00 2001 From: Derek Cormier Date: Fri, 16 Sep 2022 11:00:06 -0700 Subject: [PATCH] docs: refine documentation --- README.md | 12 +++++++----- deployment/README.md | 21 ++++++++++----------- templates/.bcr/source.template.json | 2 +- templates/README.md | 2 +- 4 files changed, 19 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index bf7d71a..a6a9b37 100644 --- a/README.md +++ b/README.md @@ -2,17 +2,19 @@ _:warning: This app is under development and is not ready to be used._ -A GitHub app that mirrors releases of your bazel ruleset to the [Bazel Central Registry](https://github.com/bazelbuild/bazel-central-registry). +A GitHub app that mirrors releases of your Bazel ruleset to the [Bazel Central Registry](https://github.com/bazelbuild/bazel-central-registry). ## Prerequisites -See the [Bzlmod User Guide](https://bazel.build/docs/bzlmod) for how to make your ruleset ready for bzlmod. +Prepare your ruleset for bzlmod by following the [Bzlmod User Guide](https://bazel.build/docs/bzlmod). ## How it works -1. [Add the app](https://github.com/apps/publish-to-bcr) to your ruleset repository and to your fork of [bazelbuild/bazel-central-registry](https://github.com/bazelbuild/bazel-central-registry). The fork can be in the same GitHub account as your ruleset or in your personal account. -1. Include these [template files](templates/README.md) to your ruleset repository. -1. Cut a release. You will be tagged in a pull request against the BCR with an entry for your module. +1. [Configure](https://github.com/apps/publish-to-bcr) the app for: + - Your ruleset repository + - A fork of [bazelbuild/bazel-central-registry](https://github.com/bazelbuild/bazel-central-registry). The fork can be in the same GitHub account as your ruleset _or_ in your personal account. +1. Include these [template files](templates/README.md) in your ruleset repository. +1. Cut a release. You will be tagged in a pull request against the BCR. ## Reporting issues diff --git a/deployment/README.md b/deployment/README.md index c6ce890..4cdbbaf 100644 --- a/deployment/README.md +++ b/deployment/README.md @@ -2,22 +2,21 @@ This will walk you through deploying the Publish to BCR app. -To deploy a new instance of the app, see [First time setup](#first-time-setup). To deploy to an already existing -instance, see [Setup for existing deployment](#setup-for-existing-deployment). +If the app has already been deployed, see [Setup for existing deployment](#setup-for-existing-deployment). ## First time setup -Follow these steps to deploy an app environment for the first time. - ### Create GitHub apps -You must create two GitHub applications, the Webhook App which will respond to ruleset release -events and publish an new entry to a fork, as well as a Bot App which posts pull requests to the -Bazel Central Registry. +Create two GitHub applications: + +1. Webhook app: responds to ruleset release events and publish an new entry to a Bazel Central Registry fork. +2. Bot App: posts pull requests to the Bazel Central Registry. -The purpose of the Bot App is to use a more restricted set of permissions when installed to -the Bazel Central Registry compared to the more permissive permissions required on the Webhook -App which is installed to ruleset repositories and BCR forks. +Technically we could use one Github app, but we want to minimize the permissions granted to any +app by the BCR. The Bot app's permissions are restricted to posting pull requests and is the one +that gets installed to the BCR. The Webhook app is installed onto ruleset repos and BCR forks, and +is responsible for pushing new entries to the fork. ### Create project @@ -90,7 +89,7 @@ Under Event subscriptions, check: - Release -### Bot App +#### Bot App Under Repository permissions, set: diff --git a/templates/.bcr/source.template.json b/templates/.bcr/source.template.json index 10e1eee..4f14819 100644 --- a/templates/.bcr/source.template.json +++ b/templates/.bcr/source.template.json @@ -1,5 +1,5 @@ { - "integrity": "**leave this alone**", + "integrity": "", "strip_prefix": "{REPO}-{VERSION}", "url": "https://github.com/{OWNER}/{REPO}/archive/refs/tags/{TAG}.tar.gz" } diff --git a/templates/README.md b/templates/README.md index 9ffecb1..01af574 100644 --- a/templates/README.md +++ b/templates/README.md @@ -67,7 +67,7 @@ The `integrity` hash will automatically be filled out by the app. ```jsonc { - "integrity": "**leave this alone**", // <-- Don't touch this + "integrity": "", // <-- Leave this alone "strip_prefix": "{REPO}-{VERSION}", "url": "https://github.com/{OWNER}/{REPO}/archive/refs/tags/{TAG}.tar.gz" }