Lock and unlock branch as part of the release process (#2145)

* Lock and unlock branch as part of the release process

This ensures that there's no way to accidentally forget that you're in the middle of the release process and make a change to the repo.

Part of #1946

* Add to reference index

* Apply suggestions from code review

Co-authored-by: Davis Vaughan <[email protected]>

* Redocument/update snapshot tests

* Document permissions

* github_lock_branch() instead of gh_lock_branch()

Looking at other function names we use "github" (vs. "gh") everywhere except `gh_token_help()`. And that is arguably correct, since you could view that function as helping the gh package get a suitable token.

* Make github_(un)lock_branch more consistent with other functions

Also, move to different file.

* More work on docs

---------

Co-authored-by: Davis Vaughan <[email protected]>
Co-authored-by: Jenny Bryan <[email protected]>

Author: 3 people

DESCRIPTION

@@ -63,4 +63,4 @@ Config/usethis/last-upkeep: 2025-04-22
 Encoding: UTF-8
 Language: en-US
 Roxygen: list(markdown = TRUE)
-RoxygenNote: 7.3.2.9000
+RoxygenNote: 7.3.3

NAMESPACE

@@ -41,6 +41,8 @@ export(git_protocol)
 export(git_remotes)
 export(git_sitrep)
 export(git_vaccinate)
+export(github_lock_branch)
+export(github_unlock_branch)
 export(issue_close_community)
 export(issue_reprex_needed)
 export(local_project)

R/github.R

@@ -224,6 +224,101 @@ use_github_links <- function(overwrite = FALSE) {
   invisible()
 }
 
+#' Lock and unlock a branch on GitHub
+#'
+#' @description
+#' These functions lock and unlock a branch on GitHub so that it's not possible
+#' for anyone to make any changes. They are used in the release checklist
+#' generated by [use_release_issue()]. The objective is to ensure that, once
+#' you've submitted your package to CRAN, you don't accidentally merge any pull
+#' requests or push any commits, while you are waiting for CRAN to get back to
+#' you. This, in turn, helps guarantee that your future Git release tag points
+#' to the correct commit.
+#'
+#' You must be an admin or an owner of the repo in order to lock/unlock
+#' a branch.
+#'
+#' @export
+#' @param branch The branch to lock/unlock. If not supplied, uses the
+#'   default branch which is usually "main" or "master", as determined by
+#'   [git_default_branch()].
+github_lock_branch <- function(branch = NULL) {
+  cfg <- github_remote_config(github_get = TRUE)
+  tr <- target_repo(cfg, role = "source", ask = FALSE)
+  branch <- branch %||% git_default_branch_(cfg)
+
+  if (!isTRUE(tr$can_admin)) {
+    ui_abort(
+      "
+      You don't seem to have {.field admin} permissions for the source repo
+      {.val {tr$repo_spec}}, which is required to lock a branch."
+    )
+  }
+
+  gh <- gh_tr(tr)
+  out <- gh(
+    "PUT /repos/{owner}/{repo}/branches/{branch}/protection",
+    branch = branch,
+    # required parameters
+    required_status_checks = NA,
+    enforce_admins = TRUE,
+    required_pull_request_reviews = NA,
+    restrictions = NA,
+    # paramater that actually does what we want
+    lock_branch = TRUE
+  )
+  result <- pluck_lgl(out, "lock_branch")
+
+  if (isTRUE(result)) {
+    ui_bullets(c(
+      "v" = "Branch {.val {branch}} is locked."
+    ))
+  }
+
+  invisible(out)
+}
+
+#' @export
+#' @rdname github_lock_branch
+github_unlock_branch <- function(branch = NULL) {
+  cfg <- github_remote_config(github_get = TRUE)
+  tr <- target_repo(cfg, role = "source", ask = FALSE)
+  branch <- branch %||% git_default_branch_(cfg)
+
+  if (!isTRUE(tr$can_admin)) {
+    ui_abort(
+      "
+      You don't seem to have {.field admin} permissions for the source repo
+      {.val {tr$repo_spec}}, which is required to unlock a branch."
+    )
+  }
+
+  gh <- gh_tr(tr)
+  # using the endpoint to update branch protection instead of the one for
+  # deletion, in order to get a response that helps us emit a good message
+  # and invisibly return something useful
+  out <- gh(
+    "PUT /repos/{owner}/{repo}/branches/{branch}/protection",
+    branch = branch,
+    # required parameters
+    required_status_checks = NA,
+    enforce_admins = TRUE,
+    required_pull_request_reviews = NA,
+    restrictions = NA,
+    # paramater that actually does what we want
+    lock_branch = FALSE
+  )
+  result <- pluck_lgl(out, "lock_branch")
+
+  if (isFALSE(result)) {
+    ui_bullets(c(
+      "v" = "Branch {.val {branch}} is unlocked."
+    ))
+  }
+
+  invisible(out)
+}
+
 has_github_links <- function(target_repo = NULL) {
   url <- if (is.null(target_repo)) NULL else target_repo$url
   github_url <- github_url_from_git_remotes(url)

R/release.R

@@ -132,13 +132,15 @@ release_checklist <- function(version, on_cran, target_repo = NULL) {
     "",
     "Submit to CRAN:",
     "",
+    todo("`usethis::github_lock_branch()`"),
     todo("`usethis::use_version('{type}')`"),
     todo("`devtools::submit_cran()`"),
     todo("Approve email"),
     "",
     "Wait for CRAN...",
     "",
     todo("Accepted :tada:"),
+    todo("`usethis::github_unlock_branch()`"),
     todo("Finish & publish blog post", type != "patch"),
     todo("Add link to blog post in pkgdown news menu", type != "patch"),
     todo("`usethis::use_github_release()`"),

_pkgdown.yml

@@ -121,6 +121,7 @@ reference:
     - starts_with("use_github")
     - git_sitrep
     - create_github_token
+    - github_lock_branch
     - gh_token_help
     - git_vaccinate
     - use_git_config

man/github_lock_branch.Rd

@@ -26,13 +26,15 @@
       
       Submit to CRAN:
       
+      * [ ] `usethis::github_lock_branch()`
       * [ ] `usethis::use_version('minor')`
       * [ ] `devtools::submit_cran()`
       * [ ] Approve email
       
       Wait for CRAN...
       
       * [ ] Accepted :tada:
+      * [ ] `usethis::github_unlock_branch()`
       * [ ] Finish & publish blog post
       * [ ] Add link to blog post in pkgdown news menu
       * [ ] `usethis::use_github_release()`
@@ -60,13 +62,15 @@
       
       Submit to CRAN:
       
+      * [ ] `usethis::github_lock_branch()`
       * [ ] `usethis::use_version('patch')`
       * [ ] `devtools::submit_cran()`
       * [ ] Approve email
       
       Wait for CRAN...
       
       * [ ] Accepted :tada:
+      * [ ] `usethis::github_unlock_branch()`
       * [ ] `usethis::use_github_release()`
       * [ ] `usethis::use_dev_version(push = TRUE)`
       * [ ] `usethis::use_news_md()`
@@ -93,13 +97,15 @@
       
       Submit to CRAN:
       
+      * [ ] `usethis::github_lock_branch()`
       * [ ] `usethis::use_version('major')`
       * [ ] `devtools::submit_cran()`
       * [ ] Approve email
       
       Wait for CRAN...
       
       * [ ] Accepted :tada:
+      * [ ] `usethis::github_unlock_branch()`
       * [ ] Finish & publish blog post
       * [ ] Add link to blog post in pkgdown news menu
       * [ ] `usethis::use_github_release()`
@@ -148,13 +154,15 @@
       
       Submit to CRAN:
       
+      * [ ] `usethis::github_lock_branch()`
       * [ ] `usethis::use_version('major')`
       * [ ] `devtools::submit_cran()`
       * [ ] Approve email
       
       Wait for CRAN...
       
       * [ ] Accepted :tada:
+      * [ ] `usethis::github_unlock_branch()`
       * [ ] Finish & publish blog post
       * [ ] Add link to blog post in pkgdown news menu
       * [ ] `usethis::use_github_release()`
@@ -184,13 +192,15 @@
       
       Submit to CRAN:
       
+      * [ ] `usethis::github_lock_branch()`
       * [ ] `usethis::use_version('major')`
       * [ ] `devtools::submit_cran()`
       * [ ] Approve email
       
       Wait for CRAN...
       
       * [ ] Accepted :tada:
+      * [ ] `usethis::github_unlock_branch()`
       * [ ] Finish & publish blog post
       * [ ] Add link to blog post in pkgdown news menu
       * [ ] `usethis::use_github_release()`