diff --git a/docs/changelog.md b/docs/changelog.md
index 56adf0fda7..d90b24c8d3 100644
--- a/docs/changelog.md
+++ b/docs/changelog.md
@@ -2,6 +2,10 @@
 
 This changelog documents user-relevant changes to the GitHub runner charm.
 
+## 2026-02-25
+
+- Add the  `How to upgrade` documentation.
+
 ## 2026-02-12
 
 - Add support to integrate with GitHub Runner planner charm with the `github_runner_planner_v0` interface.
diff --git a/docs/how-to/upgrade.md b/docs/how-to/upgrade.md
new file mode 100644
index 0000000000..9286f55341
--- /dev/null
+++ b/docs/how-to/upgrade.md
@@ -0,0 +1,9 @@
+# Upgrade
+
+In order to upgrade the charm, refresh the revision using the `juju refresh` command:
+
+```bash
+juju refresh github-runner
+```
+
+Verify if the charm is active and idle by running the `juju status --wait 1s` command.
\ No newline at end of file
diff --git a/docs/index.md b/docs/index.md
index 45855c85cf..f920514308 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -59,6 +59,7 @@ Thinking about using the GitHub runner charm for your next project? [Get in touc
   1. [Spawn OpenStack runner](how-to/openstack-runner.md)
   1. [Set up reactive spawning](how-to/reactive.md)
   1. [Comply with security requirements](how-to/comply-security.md)
+  1.  [Upgrade](how-to/upgrade.md)
   1. [Contribute](how-to/contribute.md)
 1. [Reference](reference)
   1. [Actions](reference/actions.md)