Skip to main content
Last updated: 5 Sep 2023

Modify a change note in Publishing API, Content Publisher or Whitehall

Spelling mistakes can creep into change notes, and we are often asked to correct them. The instructions below cover doing this task in Whitehall, Content Publisher and Publishing API.


Whitehall supports modifying change notes directly from the UI. The feature is hidden from publishers, but available to anyone with GDS Admin permissions. Content 2nd Line can modify the change note themselves by:

  • Appending /change_notes to the URL of the admin screen, so that the URL looks something like:<edition-id>/change_notes
  • You may need to swap out the portion after /admin/, for the word editions. For example, won’t work, but will.

Note that adding a change note is not supported in the UI. Instead, you’d need to use the app console and do something like:

ed = Edition.where(id: <relevant id>).first
ed.state = "draft"
ed.update(minor_change: false, change_note: "Change note", major_change_published_at:,12,21))
ed.state = "published"

Content Publisher

Content Publisher has a set of rake tasks for adding, deleting and editing change notes.

Publishing API

Updating change notes in Publishing API is rarely adviseable and should ONLY be done if unable to do so from the corresponding publishing app. This is to mitigate the risk of Publishing API being overwritten by the publishing app later on. Thoroughly explore your publishing app first, to see if such functionality exists (we’ve documented Whitehall and Content Publisher above), and if it doesn’t, consider building the feature in! However, in an emergency, you can edit the changenote directly in Publishing API.

  1. Ensure your access to EKS is set up:
export AWS_REGION=eu-west-1
eval $(gds aws govuk-<environment-name>-poweruser -e --art 8h)
kubectl config use-context <your-context-name>

If you have not accessed the EKS cluster before, you will need to follow the set up guide first.

  1. Connect to the Publishing API console: kubectl exec -n apps -it deploy/publishing-api -- rails c

  2. Find the document: document = Document.find_by_content_id("YOUR_CONTENT_ID_HERE")

  3. Find the document’s live edition: live_edition =

  4. Check the edition’s details hash for the change history: live_edition.details[:change_history]

If this is empty, you’ll need to follow method 1. Otherwise, follow method 2.

Method 1 (update an individual ChangeNote)

Fetch the change notes for the document:

change_notes = ChangeNote.joins(:edition).where(editions: { document: document }).order(:public_timestamp)

Select the relevant change note manually, or by searching for the note text:

change_note = change_notes.find_by("note LIKE ?", "%SUBSTRING OR FULL CHANGE NOTE TEXT%")

Update change note:

change_note.update(note: "NEW NOTE")

Finally, [send the document downstream] using the content id.

Method 2 update the details.change_history

Fetch details for edition:

details = live_edition.details

Ouput change history:


Select relevant change note manually, or by seaching for the note text:

change_note_index = details[:change_history].find_index { |change_note| change_note[:note] =~ /SUBSTRING OR FULL CHANGE NOTE TEXT/ }

Check the returned change note is correct:


Update change note:

details[:change_history][change_note_index][:note] = "New note"

Update edition:

live_edition.update(details: details)

Finally, send the document downstream using the content id.


The steps below helped us in a situation where the change note was present in the content item in both Whitehall and publishing-api, but was not being reflected on the page itself. We found this was due to the content-store not being in sync with the publishing-api. This can happen in staging due to an issue with the overnight data sync.

Things we tried:

  • purge the page from cache
  • check the Sidekiq monitoring queue to see if the document is stuck somewhere in a queue
  • look in Kibana - there might be some with the status 409 which might be due to the content-store thinking it’s got more up to date data than the publishing-api
  • compare the payload_version in publishing-api and content-store in the console, if the request from publishing-api is lower it will be ignored (also see this doc on publishing-api messages)