Skip to main content
Warning This document has not been updated for a while now. It may be out of date.
Last updated: 10 Jan 2024

Redirect a route

There are a number of different ways of applying redirects on GOV.UK. Here is a guide for choosing the right one:

That covers the service-specific redirects. We then have several options for applying redirects to most GOV.UK content:

Manually apply a redirect from any publishing app

The preferred method of creating redirects is to use the publishing app that originally published the content to set up the redirect. You can find out what exists at the incoming URL already (if anything), and which app owns the route.

Once you’ve established which app owns the route, you should see if it is possible to set up the redirect from within the app UI itself. This usually involves unpublishing the content, whereupon the app gives the option to redirect the old route to another route. This approach is preferred as it keeps the workflow and publishing history within the app, as well as correctly propagating the changes through Publishing API, Content Store and Router API.

Not all applications support unpublishing / setting redirects. In these cases, you’ll need to interact with Publishing API manually - see below.

Note that this won’t work if the thing you’re redirecting originates from the Short URL Manager: there’s a rake task for that.

You’ll need to get the content ID of the current thing that exists at the route you want to redirect from. This is generally just a case of visiting the route prefixed with /api/content to expose its Content Store information.

You may want to log into the Content Store app console in another shell:

$ gds govuk connect app-console -e production content_store/content-store

In the Content Store console, run content_item = ContentItem.find_by(content_id: "CONTENT_ID") to get a handle on the current state of the content item. If the content item already has a document_type of redirect and the redirects property has the path and destination properties you’re aiming for, then all you may need to do is nudge Content Store into talking to Router API. If your content item doesn’t have a redirect in Content Store, but you know a redirect has been applied in Publishing API, you may need to re-present the edition in Publishing API.

Assuming the redirect doesn’t exist yet, and you know no attempt has been made to redirect the item in Publishing API, your next step is to open a console on the publishing app in question. Then run this command:

GdsApi.publishing_api.unpublish(
  content_id,
  type: "redirect",
  explanation: "manually redirected by YOUR_NAME",
  alternative_path: "/new-path",
  discard_drafts: true
)

You should see a 200 response:

#<GdsApi::Response:0x00007f81feba4c30 @http_response=<RestClient::Response 200 "{\"content_i...">, @web_urls_relative_to=nil>

And you will see that the content item in the Content Store console has been updated, if you run content_item.reload in your other console.

When Content Store is updated with a new route, it talks directly to Router API. You should now be redirected when you visit the route in your browser.

Manually re-present the content item in Publishing API

Sometimes, Publishing API and Content Store can end up out of sync with one another, whereby a redirect has been applied to a content item in Publishing API but hasn’t been successfully processed by Content Store. In these cases, there are several rake tasks we can use to re-present the content item from Publishing API to Content Store.

First, you’ll need the content ID of the content item. Here we have a Publishing API console and we’ve retrieved the Unpublishing record (which has the redirect information) for the content item. We find its associated content ID and can then use this in one of the linked rake tasks.

unpublishing = Unpublishing.find_by(alternative_path: "/foo")

unpublishing.edition.content_id
=> "ddcab6e2-8985-4646-9f3d-82d2f4770186"

Manually register a route in Content Store

Sometimes, our publishing platform prevents the creation of new routes (and the addition/removal of redirects) while we are scaling up certain parts of the stack.

If the content item in Content Store is showing the correct route, but Router API is not, then re-publishing the item will not work, as the route in Content Store will be unchanged. Content Store only updates Router API if it detects the route has changed.

In such cases, you can get Content Store to register the route again, by opening the Content Store console and running:

ContentItem.find_by(base_path: "/old-path-to-be-redirected").route_set.register!

Manually apply a redirect in Router API

You might need to urgently apply a redirect, and Publishing API might have a large backlog of publishing in its downstream_high queue, making the Publishing API approach too slow.

First, connect to the Router API console:

$ gds govuk connect -e production app-console router_backend/router-api

Then update the route directly:

Route.find_by(incoming_path: "...").update!(redirect_to: "...", handler: "redirect", redirect_type: "permanent")

You should always go back and fix things properly in Publishing API afterwards, as a republish could easily undo any changes you’ve made.

Find out if the route exists

Open a router-api console:

$ gds govuk connect app-console -e production router_backend/router-api

Then search for the incoming path you are interested in:

> Route.where(incoming_path: '/path-to-item')

If a route is found, and it has the handler redirect, then there is already a redirect in place.

Find out which app owns the route

Open a Content Store console:

$ gds govuk connect app-console -e production content_store/content-store

Then search for the incoming path you are interested in:

ContentItem.find_by(base_path: "/path-to-item").publishing_app

Redirect using the Short URL Manager

If the redirect is from a URL that is not a currently-published content item, you should first look to use the Short URL Manager to create a redirect request. Requests are checked and approved by content designers, after which they are made live.

Redirects created in Short URL Manager are published via the Publishing API.

Specific Signon permissions are required to make and approve redirect requests through the Short URL Manager. Additionally, there is a advanced_options permission which enables creating redirects for pages that are already owned by other apps, creating prefix type redirects, and using non-default values for the segments_mode.

Removing a route created in the Short URL Manager

A Short URL route can be deleted from the View short URL request view in the UI of Short URL Manager.

Once the redirect is removed, the page will return a 410 Gone status.

Removing a route completely so it can be replaced with another route

Removing a route in the previous section returns a 410 Gone status - this means that the URL can not be reused by another publication as the route is still being used.

To completely remove a route requires using the Rails console for several different apps using EKS.

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

To access an app’s Rails console you’ll need to set your region and context as below (swapping out the environment as appropriate):

export AWS_REGION=eu-west-1
eval $(gds aws govuk-integration-poweruser -e --art 8h)
kubectl config use-context <your-context-name>

You can then access an app’s Rails console using the following command:

kubectl exec -n apps -it deploy/<app-name> -- rails c

Removing the route, we need to know the slug that should be deleted. These examples use /example-path.

Delete the route in router-api:

Route.where(incoming_path: "/example-path").delete

In publishing-api, delete the reservation that makes sure that the route can’t be used by any other app:

PathReservation.find_by(base_path: "/example-path").delete

In content-store and draft-content-store, remove the content item that used to inhabit the URL:

ContentItem.find_by(base_path: "/example-path").delete

You should now be able to replace the route with another one. For documents published in Mainstream Publisher, update and republish the content that should now sit at /example-path.

(In Mainstream Publisher the edition id can be found at the end of the URL. For example, the edition found at publisher.publishing.service.gov.uk/editions/5fb53d8fd3bf7f626687198c has the edition id 5fb53d8fd3bf7f626687198c.)

edition = Edition.find("<edition id>")

UpdateWorker.perform_async(edition.id.to_s)

RepublishWorker.perform_async(edition.id.to_s)

For documents published in other publishing apps that are not Mainstream Publisher, the instructions will differ.

The final step is to clear the cache for the routes.

Fixing incorrect Corporate Information page redirects

There have been a few occasions where Corporate Information pages have started redirecting the English version to a translation. Should this happen, the redirects can be identified with:

Route.where(incoming_path: /\/about/).each do |route|
  puts "#{route.id} #{route.incoming_path} -> #{route.redirect_to}" if route.handler == "redirect"
end

That will list the id and paths for each redirect. Redirects from the English version to a translation, for example:

579a109cd068b406250014e4 /government/organisations/companies-house/about/access-and-opening -> /government/organisations/companies-house/about/access-and-opening.cy

…can be deleted with

Route.find('579a109cd068b406250014e4').destroy

The deleted routes will take effect after a short delay (for Router instances to poll and apply updates).

Redirects for HMRC manuals

There are rake tasks for redirecting HMRC manuals and HMRC manual sections, which can be found in the hmrc-manuals-api repo.

An example of redirecting a HMRC manual section to another section would be to run redirect_hmrc_section[original-parent-manual-slug,original-section-slug,new-parent-manual-slug,new-section-slug]

Redirects from campaign sites

The campaigns platform is a WordPress site managed by GDS (Business, Priority Response and Campaigns team) and supported by dxw. Redirects from a *.campaign.gov.uk site require a support ticket. You should contact govuk.campaigns@digital.cabinet-office.gov.uk to raise a support ticket.