Releasing Grafana Loki

Wed, 06 Sep 2023 12:47:18 +0000

Releasing Grafana Loki

This document is a series of instructions for core Grafana Loki maintainers to be able to publish a new Loki release.

Prerequisites

Each maintainer performing a release should perform the following steps once before releasing Loki.

Signing Tags and Commits

Add Existing GPG Key to GitHub

First, Navigate to your user’s SSH and GPG keys settings page. If the GPG key for the email address used to commit with Loki is not present, follow these instructions to add it:

Run gpg --armor --export <your email address>
Copy the output.
In the settings page linked above, click “New GPG Key”.
Copy and paste the PGP public key block.

Signing Commits and Tags by Default

To avoid accidentally publishing a tag or commit without signing it, you can run the following to ensure all commits and tags are signed:

git config --global commit.gpgSign true
git config --global tag.gpgSign true

macOS Signing Errors

If you are on macOS and using an encrypted GPG key, the gpg-agent may be unable to prompt you for your private key passphrase. This will be denoted by an error when creating a commit or tag. To circumvent the error, add the following into your ~/.bash_profile or ~/.zshrc, depending on which shell you are using:

export GPG_TTY=$(tty)

Performing the Release

Create a new branch to update CHANGELOG.md and references to version numbers across the entire repository (e.g. README.md in the project root).
Modify CHANGELOG.md with the new version number and its release date.
List all the merged PRs since the previous release. This command is helpful for generating the list (modifying the date to the date of the previous release): curl https://api.github.com/search/issues?q=repo:grafana/loki+is:pr+"merged:>=2019-08-02" | jq -r ' .items[] | "* [" + (.number|tostring) + "](" + .html_url + ") **" + .user.login + "**: " + .title'
Go through docs/ and find references to the previous release version and update them to reference the new version.
Without creating a tag, create a commit based on your changes and open a PR for updating the release notes.
1. Until 852 is fixed, updating Helm and Ksonnet configs needs to be done in a separate commit following the release tag so that Helm tests pass.
Merge the changelog PR.
Create a new tag for the release.
1. Once this step is done, the CI will be triggered to create release artifacts and publish them to a draft release. The tag will be made publicly available immediately.
2. Run the following to create the tag:
  Bash
```
RELEASE=v1.2.3 # UPDATE ME to reference new release
git checkout release-1.2.x # checkout release branch
git pull
git tag -s $RELEASE -m "tagging release $RELEASE"
git push origin $RELEASE
```
Watch Drone and wait for all the jobs to finish running.

Updating Helm and Ksonnet configs

These steps should be executed after the previous section, once CircleCI has finished running all the release jobs.

Run bash ./tools/release_prepare.sh
When prompted for the release version, enter the latest tag.
When prompted for new Helm version numbers, the defaults should suffice (a minor version bump).
Commit the changes to a new branch, push, make a PR, and get it merged.

Publishing the Release Draft

Once the previous two steps are completed, you can publish your draft!

Go to the GitHub releases page and find the drafted release.
Edit the drafted release, copying and pasting notable changes from the CHANGELOG. Add a link to the CHANGELOG, noting that the full list of changes can be found there. Refer to other releases for help with formatting this.
Optionally, have other team members review the release draft so you feel comfortable with it.
Publish the release!

Versioning Loki docs on Grafana Website

Loki docs are versioned. Follow the below steps to version Loki docs for this release.

NOTE: Here $LOCAL_LOKI_PATH is your local path where Loki is checked out with correct $VERSION

Clone Grafana website repo
Create new branch git checkout -b $VERSION (replace $VERSION with current release version. e.g: v2.5.0)
Run mv content/docs/loki/next content/docs/loki/next.main
Run mkdir content/docs/loki/next
Run cp -R $LOCAL_LOKI_PATH/docs/sources/* content/docs/loki/next
Run scripts/docs-release.sh loki latest next
Run scripts/docs-release.sh loki $VERSION latest
Run mv content/docs/loki/next.main content/docs/loki/next
Update version_latest to $VERSION in content/docs/loki/_index.md
Docs will be generated for this release.
Create PR and Merge it after approval.

Releasing Loki Build Image

Wed, 06 Sep 2023 12:47:18 +0000

Releasing Loki Build Image

The loki-build-image is the Docker image used to run tests and build Grafana Loki binaries in CI.

The build and publish process of the image is triggered upon a merge to main if any changes were made in the folder ./loki-build-image/.

To build and use the loki-build-image:

Step 1

create a branch with the desired changes to the Dockerfile
update the version tag of the loki-build-image pipeline defined in .drone/drone.jsonnet (search for pipeline('loki-build-image')) to a new version number (try to follow semver)
run DRONE_SERVER=https://drone.grafana.net/ DRONE_TOKEN=<token> make drone and commit the changes to the same branch
1. the <token> is your personal drone token, which can be found by navigating to https://drone.grafana.net/account.
create a PR
once approved and merged to main, the image with the new version is built and published
- Note: keep an eye on https://drone.grafana.net/grafana/loki for the build after merging (example)

Step 2

create a branch
update the BUILD_IMAGE_VERSION variable in the Makefile
run loki-build-image/version-updater.sh <new-version> to update all the references
run DRONE_SERVER=https://drone.grafana.net/ DRONE_TOKEN=<token> make drone to update the Drone config to use the new build image
create a new PR

Maintaining on Grafana Labs

Releasing Grafana Loki

Releasing Grafana Loki

Prerequisites

Signing Tags and Commits

Add Existing GPG Key to GitHub

Signing Commits and Tags by Default

macOS Signing Errors

Performing the Release

Updating Helm and Ksonnet configs

Publishing the Release Draft

Versioning Loki docs on Grafana Website

Releasing Loki Build Image

Releasing Loki Build Image

Step 1

Step 2