Manual

Common tasks

How to...

• Create a Local Transaction
• Deploy an emergency banner
• Deploy non-emergency global banner
• Post a message on the status page
• Purge a page from cache
• Query Kibana (includes useful queries)
• Run a rake task

Learn

• Responsibilities of a Tech Lead
• What is GOV.UK Emergency Alerts?

A/B testing

How to...

• Run an A/B or multivariate test

Learn

• How A/B testing works

Accounts

How to...

• Access apps on the shared Heroku account
• Manage Signon user/API accounts and access tokens

Applications

How to...

• Application ownership
• Configure linting
• Create a Local Transaction
• Incorrect postcode data
• Name a new application or gem
• Retire a repo
• Retire an application
• Set up a new Rails application
• Update popular links

Learn

• Architectural deep-dive of GOV.UK
• Architectural summary of GOV.UK
• Architecture overview of GOV.UK applications
• Conventions for Rails applications

Assets

How to...

• Manage assets

Learn

• Assets: how they work

Authentication and authorisation

Learn

• Rules for getting production access

AWS

How to...

• Google Cloud Platform (GCP)
• How to check and commit code to AWS CodeCommit
• How to raise a support ticket with AWS

Backups

How to...

• Backup and restore databases in AWS RDS
• Fix out-of-date search indices
• Restore Elasticsearch indices from backup

Learn

• Data backups in GOV.UK
• Environment data sync

CDN & Caching

How to...

• Purge a page from cache

Learn

• Our content delivery network (CDN)

Content Data

Learn

• Content Data architecture

Cookies

Learn

• Cookie consent on GOV.UK
• Cookies and sessions in GOV.UK frontend apps

data.gov.uk

How to...

• Common support tasks for data.gov.uk and CKAN
• Deployments for data.gov.uk

Learn

• Architecture of data.gov.uk
• Data.gov.uk Contracts Archive

Databases

How to...

• How to query MySQL database on EKS
• MongoDB infra commands

Dependencies

How to...

• Manage dependencies with Dependabot

Learn

• Guidance for upgrades to Rails 8.0
• How to upgrade Rails
• Policy on keeping software current

Deployment

How to...

• Deploy Static
• Deploy when GitHub is unavailable
• Deployments
• Fall back to AWS CloudFront
• GOV.UK content mirrors
• Publish special routes
• Run a rake task
• Set up Heroku review apps for pull requests

Learn

• The development pipeline

Docker

Learn

• Intro to GOV.UK Docker
• Intro to GOV.UK Docker (Advanced)

Documentation

How to...

• Review a page in this manual

Learn

• Documentation style guide
• READMEs for GOV.UK applications

Emails

How to...

• Handle exemptions to the ‘Get emails about this page’ feature

Learn

• Document Collection emails - a special case
• Email notifications: how they work
• Email signup journeys and email subscriptions across GOV.UK
• How we use GOV.UK Notify

Emergency Alerts

How to...

• Rotate Fastly automation token for Emergency Alerts application

Learn

• What is GOV.UK Emergency Alerts?

Frontend

How to...

• Deploy a banner to certain pages
• Find a rails template based on a GOV.UK URL or vice verca
• How to remove jQuery from JavaScript
• How to test with Assistiv Labs
• Migrate to Dart Sass from LibSass
• Track frontend performance with SpeedCurve

Learn

• Analytics on GOV.UK
• Frontend architecture
• GA4 Implementation Record
• Google Tag Manager change process
• Guidance and tools for digital accessibility
• Local frontend development
• The component system
• Which browsers we support

GitHub

How to...

• Configure a new GOV.UK repository
• Make a GitHub repo private
• Merge a Pull Request

Learn

• How GOV.UK uses GitHub

GOV.UK Account

Learn

• How does the GOV.UK Account work?

Incident management

Learn

• GOV.UK Technical On-Call Support

Incident response

Learn

• Communicate when Slack is unavailable

Incidents

How to...

• Post a message on the status page
• So, you're having an incident

Infrastructure

How to...

• Add a new Ruby version
• Databases on GOV.UK
• Manage Amazon MQ
• Manage OpenSearch on AWS
• Provision machines for data science research
• Raise issues with Reliability Engineering
• Retrieve shared credentials from AWS Secrets Manager

Learn

• Domain Name System (DNS) records
• GOV.UK's environments (integration, staging, production)
• Organisations API
• Rate Limiting
• Terraform Cloud

Learning GOV.UK

How to...

• Ask for help
• Get started developing on GOV.UK
• Learn how GOV.UK works

Learn

• Dictionary of concepts on GOV.UK
• How to be a good buddy
• Responsibilities of a Tech Lead
• Where to find what documentation
• Zendesk

Licensing

Learn

• Access to Licensify for Third Parties
• Licensify - supporting licensing

Logging

How to...

• Query CDN logs
• Query Kibana (includes useful queries)
• View GOV.UK logs in Logit

Learn

• How logging works on GOV.UK
• Request tracing

Monitoring and alerting

How to...

• Debug underperforming search
• GOV.UK Chat Alerts
• How we handle errors
• Pingdom
• Rotate Fastly automation token for Prometheus exporter
• Router error ratio too high
• Signon API user token expires soon
• Travel Advice or Drug and Medical Device email alerts not sent
• Whitehall error ratio too high

Learn

• Graphite and deployment dashboards
• PagerDuty
• Pingdom Bouncer canary check
• Sentry
• Sidekiq

Packaging

How to...

• Publish a Ruby gem
• Retire a gem

Publishing

How to...

• Add a new document type
• Add an organisation's brand colour or logo
• Add Historical Accounts
• Add support for a new language on GOV.UK
• Change a slug and create redirect in Whitehall
• Change a specialist document base path
• Content that doesn't show up correctly in search or list pages
• Debug published documents with incorrect links
• Deploy an emergency banner
• Deploy non-emergency global banner
• Find usage of Govspeak in content
• Help with publishing content
• If documents aren't live after being published
• Make a new document type available to search
• Modify a change note in Publishing API, Content Publisher or Whitehall
• Redirect an HTML attachment's URL in Whitehall
• Reindex an Elasticsearch index
• Remove a change note
• Rename a country
• Republish content
• Support government changes
• Upload HMRC PAYE files

Learn

• Finder schema guidance
• How the draft stack works
• How the topic taxonomy works
• How the world taxonomy works
• Related links
• What data we expose as schema.org structured data

Routing

How to...

• Change an organisation's slug
• Redirect a route

Security

How to...

• Content Security Policy on GOV.UK
• Pentests
• Set up a YubiKey
• Web Application Firewall (WAF) configuration

Team tools

How to...

• How to add popular GOV.UK Slack integrations

Testing

How to...

• Run a load test with k6
• Test & build a project with GitHub Actions

Learn

• Brakeman
• CodeQL
• Dependency Review
• How we test GOV.UK
• Pact Testing
• Security Alerts Guidance

Transition

How to...

• Configure transition mappings for a site
• Remove a site from the Transition tool
• Request Fastly TLS certificate
• Transition a site to GOV.UK

Learn

• Transition architecture

Uncategorised

Learn

• GOV.UK Search: how it works
• GOV.UK's sitemap