# Adding details to code rollout events

Buoyant Cloud automatically detects rollouts to workloads on any Kubernetes
cluster that it's connected to, and creates an event to record this change.

You can augment the rollout event by setting Kubernetes annotations on the
Deployment object during rollout time. These annotations are:

| Annotation                          | Description                                                                                                                                                                                                             |
| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `buoyant.cloud/version`             | The version of the release, e.g. _1.23._ (If unset, the SHA will be used). This will appear in the title of the rollout event.                                                                                          |
| `buoyant.cloud/deployer`            | The email address (or, for GitHub users, GitHub user id) of the person who triggered the rollout.                                                                                                                       |
| `buoyant.cloud/repo-owner`          | The GitHub Org of the deployed code, e.g. _BuoyantIO._                                                                                                                                                                  |
| `buoyant.cloud/repo-name`           | The name of the Github repo for this service                                                                                                                                                                            |
| `buoyant.cloud/git-sha`             | The corresponding git SHA of the deployed code, e.g. _abc123._                                                                                                                                                          |
| `buoyant.cloud/rollout-description` | Any additional information you may want to include for the rollout, e.g. a changelog. This field is in Markdown format and the maximum length is 64k. This will appear in the "Details" field on the event detail page. |

Each annotation is optional, and will augment the corresponding rollout event
object with extra information. For example, setting the `deployer` annotation
will allow Buoyant Cloud to display _who_ triggered the rollout; adding the
`repo-owner`, `repo-name`, and `git-sha` annotations will allow Buoyant Cloud to
link to the GitHub commit, and so on.

## Example: Automatic changelog

One potential use of the `rollout-description` field is to include an
automatically-generated changelog representing the changes in this rollout. For
example, the following `git` command will produce a simple Markdown changelog
from `$PREV_COMMIT_SHA` to `$THIS_COMMIT_SHA`, including links to the
corresponding commit on `$GITHUB_REPO_URL`:

```bash
git log $PREV_COMMIT_SHA..$THIS_COMMIT_SHA1\\ --pretty=format:'* %s ([%aE, %ar]($GITHUB_REPO_URL/commit/%H))'
```

This generates a bulleted list. If you prefer a non-bulleted list, note that
Buoyant Cloud 's Markdown renderer produces "classic" Markdown and does not
automatically add linebreaks. Thus, if you remove the `*` prefix, you will need
to add a `<br/>` (or two spaces) at the end of each line.