Merge pull request git-lfs#5987 from chrisd8088/release-doc-updates

Add security patch release process documentation

Author: chrisd8088

docs/howto/release-git-lfs.md

@@ -75,7 +75,7 @@ case we are releasing a MAJOR version.  Conversely, if `P` is not equal
 to zero, we are releasing a PATCH version.
 
   1. Upgrade the Go version used in the `git-lfs/build-dockers` repository
-     to the latest available patch release with the same major and minor
+     to the latest available PATCH release with the same major and minor
      version numbers as the Go version used in this repository's GitHub
      Actions workflows.
 
@@ -152,7 +152,7 @@ to zero, we are releasing a PATCH version.
        does not need to be signed (but must be annotated).  Check that the
        local version of Go is equivalent to the most recent one used by the
        GitHub Actions workflows for the release branch, which may be different
-       from that used on the `main` branch.  For a patch release in particular
+       from that used on the `main` branch.  For a PATCH release in particular
        you may need to downgrade your local Go version.  The build artifacts
        will be placed in the `bin/releases` directory and may be uploaded
        into the PR from there:
@@ -225,7 +225,8 @@ to zero, we are releasing a PATCH version.
      Actions
      [workflow](https://github.com/git-lfs/git-lfs/actions/workflows/release.yml),
      and then unpack the file at the top level of the repository:
-     ```
+
+     ```ShellSession
      $ rm -rf bin/releases
      $ unzip /path/to/release-assets.zip
      ```
@@ -234,7 +235,7 @@ to zero, we are releasing a PATCH version.
      The `script/upload` utility will create a new draft release announcement
      and then upload the release assets and attach them to the announcement:
 
-     ```
+     ```ShellSession
      $ script/upload --skip-verify vM.N.P
      ```
 
@@ -285,7 +286,7 @@ to zero, we are releasing a PATCH version.
      should correspond with the packaged artifact containing the new
      release's source files which is available at the given URL:
 
-     ```
+     ```ShellSession
      $ brew tap homebrew/core
      $ brew bump-formula-pr \
          --url https://github.com/git-lfs/git-lfs/releases/download/vM.N.P/git-lfs-vM.N.P.tar.gz \
@@ -300,7 +301,7 @@ When building a PATCH release, we cherry-pick merges from `main` to the
 and then use that branch as the base for the PATCH release.
 
   1. Upgrade or downgrade the Go version used in the `git-lfs/build-dockers`
-     repository to the latest available patch release with the same major
+     repository to the latest available PATCH release with the same major
      and minor version numbers as the Go version used to build the Git LFS
      `vM.N.(P-1)` release.
 
@@ -313,7 +314,7 @@ and then use that branch as the base for the PATCH release.
      ```
 
      If the release branch already exists because this is not the first
-     patch release for the given MINOR (or MAJOR) release, simply checkout
+     PATCH release for the given MINOR (or MAJOR) release, simply checkout
      the `release-M.N` branch, and ensure that you have the latest changes
      from the remote.
 
@@ -336,3 +337,281 @@ and then use that branch as the base for the PATCH release.
 
   5. Then follow the [guidelines](#building-a-release) above, using the
      `release-M.N` branch as the base for the new PATCH release.
+
+### Building security PATCH versions
+
+In our public security [policy](../../SECURITY.md) we request that
+potential vulnerabilities in the Git LFS client be reported to us
+via email.  Users sometimes also choose to open draft GitHub security
+advisories, although we do not encourage that option.
+
+If we determine that such a report is valid, we develop a PATCH release
+version of the client with a remediation for the security issue,
+following the steps below.
+
+  1. Open a new draft security advisory, fill out the relevant
+     details in the
+     [template](https://github.com/git-lfs/git-lfs/security/advisories/new),
+     and request a CVE identifier.
+
+  2. Create a temporary private fork of this repository from the draft
+     security advisory page, and use the fork to develop a resolution
+     of the vulnerability.
+
+  3. Create two PRs in the private fork, one to remediate the vulnerability
+     in the `main` development branch of the public `git-lfs/git-lfs`
+     repository, and one to do so in the appropriate `release-M.N` branch.
+
+     The PR which targets the release branch should have a final, extra
+     commit which adds an entry for the new PATCH release version in the
+     `CHANGELOG.md` file, describing the release and the security fix it
+     contains.  This commit should also include the changes generated
+     by the `script/update-version vM.N.P` command, as per the second step
+     in our standard release process.
+
+     If the `release-M.N` branch does not exist in the public repository,
+     create it as per our regular PATCH release process, and then create
+     the second PR in the private fork against the new branch.  Be prepared
+     to proceed relatively quickly, since the appearance of the new branch
+     serves as a public notice that we may be publishing a PATCH release
+     shortly.
+
+  4. From the draft security advisory page, use the "Merge pull requests"
+     option to merge both PRs simultaneously.
+
+     Note that both the release branch and the `main` branch in the private
+     fork must be up-to-date with the corresponding branches in the public
+     repository in order for the GitHub UI to determine whether the PRs have
+     no merge conflicts.
+
+  5. Publish the security advisory.
+
+  6. Follow our standard release process, starting with the step in which
+     we create a GPG-signed tag named `vM.N.P` on the merge commit to the
+     `release-M.N` branch.
+
+  7. After publication of the new release, update the `git-lfs.com` home
+     page with a banner message regarding the security PATCH release.
+     Place the banner at the top of the `_includes/home/secondary.html`
+     file in the `git-lfs/git-lfs.github.com` repository.  Use the GHSA
+     identifier from the security advisory, and remove any previous
+     security message banners.
+
+     ```html
+     <div class="column">
+       <a class="dot-com-announcement" data-ga-params="banner"
+         href="https://github.com/git-lfs/git-lfs/security/advisories/GHSA-abcd-1234-wxyz">
+         Git LFS security update: <span>All users should update to M.N.P or newer</span>.</a>
+       </a>
+     </div>
+     ```
+
+  8. Create a new discussion in the "Announcements" section of the GitHub
+     discussion [forum](https://github.com/git-lfs/git-lfs/discussions)
+     describing the security PATCH release, and pin the discussion for
+     all categories in the forum.
+
+### Building security PATCH versions under embargo
+
+When coordinating the release of a security patch with one or more
+other projects, we must not follow the processes described above as
+they depend on the GitHub Actions release workflow in our public
+`git-lfs/git-lfs` repository.  Instead, we use a private repository
+with a modified release workflow to build the binaries and packages
+for our new version so that we can share them with the other projects
+in advance of the coordinated release date.
+
+  1. Open a draft security advisory, apply for a CVE identifier, and
+     create a temporary private fork from the advisory page.  Develop a
+     resolution of the vulnerability in the private fork.  These initial
+     steps are the same as those of our non-embargoed security PATCH
+     release process.
+
+  2. Create one PR in the private fork to remediate the vulnerability
+     in the `main` development branch of the public repository.
+
+  3. Create a branch in the private fork from the appropriate
+     `release-M.N` branch, or if that does not yet exist, from the
+     appropriate `vM.N.0` tag, and add the necessary changes to remediate
+     the vulnerability.
+
+     This branch should have one extra, final commit which adds an entry
+     for the new PATCH release version in the `CHANGELOG.md` file,
+     describing the release and the security fix it contains.  This
+     commit should also include the changes generated by the
+     `script/update-version vM.N.P` command, as per the second step
+     in our standard release process.
+
+  4. Pull this branch from the private fork of the public repository
+     and push it into a separate private repository which has a fresh copy
+     of the public `git-lfs/git-lfs` repository, and for which our full
+     CI and release GitHub Actions workflows are configured and enabled.
+
+     Note that the private fork created from the draft security advisory
+     will not execute GitHub Actions jobs, and so we require the use of
+     a separate private repository to run a modified release workflow.
+
+  5. If the `release-M.N` branch does not exist, create it in the
+     separate private repository from the `vM.N.0` tag, as described
+     in the second step of our regular PATCH release process.
+
+  6. Merge the branch containing the security fix and the commit with the
+     new `CHANGELOG.md` entry (and `script/update-version vM.N.P` changes)
+     into the `release-M.N` branch, and sign the merge commit with your
+     GPG key:
+
+     ```ShellSession
+     $ git checkout release-M.N
+     $ git merge --no-ff -S \
+         -m "Merge pull request from GHSA-abcd-1234-wxyz" \
+         -m "release: M.N.P" \
+         branch-with-fix-and-changelog
+     ```
+
+     Use the GHSA identifier from the draft security advisory in the
+     merge commit's description.
+
+  7. Create a GPG-signed tag named `vM.N.P` on the merge commit, using
+     the same command from the equivalent step of our standard release
+     process:
+
+     ```ShellSession
+     $ git tag -s vM.N.P -m vM.N.P
+     ```
+
+  8. Check out the `main` branch of the private repository and make
+     the following revisions to the `.github/workflows/release.yml` file,
+     and then push these changes back to the private repository's `main`
+     branch.
+
+     First, change the `on` value to `workflow_dispatch`:
+
+     ```diff
+     -on:
+     -  push:
+     -    tags: '*'
+     +on: workflow_dispatch
+     ```
+
+     Set the version of Go in each `matrix` context to the same version
+     used in the Dockerfiles from our `git-lfs/build-dockers` repository.
+
+     Replace the `${{ github.ref }}` context wherever it appears with the
+     `vM.N.P` tag:
+
+     ```diff
+     -    ref: ${{ github.ref }}
+     +    ref: vM.N.P
+     ```
+
+     Revise the `build-docker` and `build-docker-arm` jobs so they do not
+     upload the Linux packages generated by the `docker/run_dockers.bsh`
+     script to Packagecloud by running the `script/packagecloud.rb` utility.
+     Change the jobs to instead upload the Linux packages as job artifacts;
+     for instance, for the `build-docker` job:
+
+     ```yaml
+         - uses: actions/upload-artifact@v4
+           with:
+             name: docker-assets
+             path: |
+               repos/**/*.deb
+               repos/**/*.rpm
+     ```
+
+     Make sure to use distinct artifact `name`s for each of these jobs,
+     i.e., `docker-assets` and `docker-arm-assets`.
+
+  9. Push the `vM.N.P` tag to the private repository, and then cancel
+     the GitHub Actions job which runs from the release workflow.
+
+     (This workflow will run because the tag includes our normal
+     GitHub Actions workflow definitions without the changes made in
+     the previous step, since those exist only on the `main` branch,
+     and we do not want to include these temporary workflow changes in
+     the security release itself.)
+
+     Confirm that the CI workflow job succeeds.
+
+ 10. From the private repository's GitHub Actions page, manually dispatch
+     the release workflow.
+
+ 11. When the manually-dispatched job is complete, download the
+     `release-assets`, `docker-assets`, and `docker-arm-assets` archive
+     files from the "Artifacts" section of the job's "Summary" page.
+
+     Share the relevant binaries from the archive files with the other
+     collaborating projects during the embargo period.
+
+ 12. Before the embargo is due to the lifted, unpack the `release-assets`
+     archive file at the top level of this repository and use the
+     `script/upload` utility to create a draft release announcement and
+     attach the release assets to it, just as for a standard release:
+
+     ```ShellSession
+     $ rm -rf bin/releases
+     $ unzip /path/to/release-assets.zip
+
+     $ script/upload --skip-verify vM.N.P
+     ```
+
+ 13. When the embargo is lifted, use the "Merge pull requests" option
+     on the draft security advisory page to merge the PR with the security
+     fix into the `main` branch of the public repository.
+
+     Note that the `main` branch in the private fork must be up-to-date
+     with the corresponding branch in the public repository in order for
+     the GitHub UI to determine whether the PR has no merge conflicts.
+
+ 14. Publish the security advisory.
+
+ 15. Pull the `release-M.N` branch and `vM.N.P` tag from the private
+     repository where the release workflow was run manually, and push
+     them into the public `git-lfs/git-lfs` repository.
+
+     Immediately cancel the GitHub Actions job which runs from the
+     release workflow in the public repository.
+
+     Note that cancelling the release workflow job is important, since
+     it will otherwise build new versions of the RPM and Debian Linux
+     packages and publish them to Packagecloud.
+
+ 16. Upload to Packagecloud the RPM and Debian Linux packages in the
+     `docker-assets` and `docker-arm-assets` archive files created earlier
+     by the manual release workflow job.
+
+     Note that the `script/packagecloud.rb` utility requires the
+     `PACKAGECLOUD_TOKEN` environment variable to contain the current
+     Packagecloud account credential token.
+
+     ```ShellSession
+     $ mkdir repos
+     $ unzip -d repos /path/to/docker-assets.zip
+     $ unzip -d repos /path/to/docker-arm-assets.zip
+
+     $ gem install packagecloud-ruby
+     $ PACKAGECLOUD_TOKEN="<token>" script/packagecloud.rb
+     ```
+
+ 17. Finalize the release process using the `script/upload` utility with
+     the `--finalize` option.  The script will add GPG signatures to the
+     `hashes` and `sha256sums` files and then upload the signed files:
+
+     ```ShellSession
+     $ script/upload --finalize vM.N.P
+     ```
+
+ 18. Publish the release announcement.
+
+ 19. Update the `_config.yml` file in the `git-lfs/git-lfs.github.com`
+     repository with the new `M.N.P` release version and push the change,
+     as described in the final steps of our standard release process.
+
+     In addition, update the `_includes/home/secondary.html` file with
+     a banner message regarding the security PATCH release, and push
+     the change.
+
+ 20. Create a new discussion in the "Announcements" section of the GitHub
+     discussion [forum](https://github.com/git-lfs/git-lfs/discussions)
+     describing the security PATCH release, and pin the discussion for
+     all categories in the forum.