Skip to content
Alpha

This site is an alpha version and is still being developed in the open - your feedback will help us improve it. See the roadmap. Last updated: 14 October 2026.

Version in force: 0.3.0 (6 October 2026).

Updating the Defra architecture site: a guide for the team

Start here if you are new to updating this site. It explains how the site is built, the rules every change follows, which file to edit for each kind of change and how a change gets published.

Draft - to be confirmed

Parts of this page, such as names, timings and thresholds, are still being confirmed by the architecture team. Use it as a guide, and check with your solution design authority before relying on the detail.

For the exact fields, templates and commands, use the contribute page. This guide gives you the overview.

How the site is built

The site is generated from Markdown and YAML files in the DEFRA/architecture repository. Nobody edits HTML. Every change goes through a pull request, is checked automatically, and is published when it is merged to main.

  • MkDocs with the Material theme. Settings and the navigation are in mkdocs.yml. A new page does not appear in the navigation until you add it there.
  • Pages are Markdown with front matter. Each guardrail page holds its guardrails as text (heading, Must, Should or Could badge, why and how to meet it) and their metadata as YAML at the top of the file: phases, lead roles, evidence, and links to the Service Standard, the Technology Code of Practice (TCoP) and Secure by Design.
  • Data is YAML. Capabilities, non-functional requirements (NFRs), service tiers, the delivery lifecycle, platforms, roles, approvals and exceptions are YAML files, not pages. Pages show them through markers such as `

Showing 110 of 110 guardrails

PrincipleGR-PRIN-01EndorsedArchitecture principles

Delivery-focused architecture

Architecture is a service to delivery teams. Architecture principles will support seamless delivery pipelines, enabling rapid, low-risk releases.

PrincipleGR-PRIN-02EndorsedArchitecture principles

Design for users

Create intuitive, accessible, user-friendly and consistent solutions that simplify access and improve user experience.

PrincipleGR-PRIN-03EndorsedArchitecture principles

Maximise value, minimise waste

Focus on delivering greater value to customers and citizens through reuse of common capabilities and effective technology management.

PrincipleGR-PRIN-04EndorsedArchitecture principles

Clean data, clear decisions

Ensure data is clean, accurate, consistent, timely and accessible, using AI to enhance data quality, integration and insights.

PrincipleGR-PRIN-05EndorsedArchitecture principles

Connect and collaborate

Create a flexible, connected and interoperable ecosystem through integration, automation and AI, to give streamlined user journeys and seamless data flows.

PrincipleGR-PRIN-06EndorsedArchitecture principles

Secure today, safe tomorrow

Implement robust security measures to protect data and systems and maintain a secure environment.

PrincipleGR-PRIN-07EndorsedArchitecture principles

Empower to innovate

Give the business the knowledge and tools to use its creativity to deliver innovative change.

PrincipleGR-PRIN-08EndorsedArchitecture principles

Right tools, right place

Equip staff with the tools and devices they need to communicate and operate effectively in all conditions.

ShouldGR-AI-01DraftArtificial intelligence

Consider AI first

When designing a service or process, actively explore whether AI can improve quality, productivity, user experience or outcomes before choosing a traditional approach, and record the reasoning either way.

Evidence
ADR recording the AI options considered and why they were or were not used
Automated check
Manual
Phases
Discovery, Alpha
Led by
Product manager, Service designer
MustGR-AI-02DraftArtificial intelligence

Use approved AI services and tenancies

Services you build run their AI in Defra's cloud tenancies or under approved enterprise agreements. When anyone uses an AI tool, they put Defra data into it only as the using data with AI rules in the AI digital toolkit allow - for example, never OFFICIAL-SENSITIVE or personal data in a public consumer tool.

Evidence
List of the AI services the service uses and the Defra tenancy or enterprise agreement each runs under
Automated check
Manual
Phases
Discovery, Alpha, Beta, Live
Led by
Technical architect, Security architect
MustGR-AI-03DraftArtificial intelligence

Keep a human accountable

Decisions with legal or significant effects on people or organisations - such as licensing, enforcement or payments - have meaningful human oversight, and the ability to challenge.

Evidence
Design of the human oversight and challenge route, tested with users
Automated check
Manual
Phases
Alpha, Beta, Live
Led by
Service designer, User researcher
MustGR-AI-04DraftArtificial intelligence

Be transparent

Publish an Algorithmic Transparency Recording Standard record for algorithmic tools that meet its scope, and tell users when they are interacting with AI.

Evidence
Link to the published Algorithmic Transparency Recording Standard record and the AI notice shown to users
Automated check
Manual
Phases
Beta, Live
Led by
Content designer, Interaction designer
ShouldGR-AI-05DraftArtificial intelligence

Evaluate, monitor and threat model

Evaluate models for accuracy, bias and safety before release, monitor them in live, and include AI-specific threats (prompt injection, data leakage, model abuse) in your threat model.

Evidence
Model evaluation results for accuracy, bias and safety, live monitoring, and a threat model that covers AI-specific threats
Automated check
Manual
Phases
Alpha, Beta, Live
Led by
Data architect, Security architect
ShouldGR-AI-06DraftArtificial intelligence

Talk to the TDA about novel use

Novel uses of AI, and any use of generative AI in decision making, are reviewed by the Technical Design Authority.

Evidence
Technical Design Authority review outcome recorded in the ADR
Automated check
Manual
Phases
Discovery, Alpha
Led by
Technical architect
ShouldGR-AI-07DraftArtificial intelligence

Suppliers use AI coding assistants openly and safely

Delivery partners who use AI coding assistants on Defra work agree which tools they use with Defra, use them only under terms that meet GR-AI-02, have a person review every change before it is merged, and say in pull requests or delivery reports where AI did significant work.

Evidence
Supplier's agreed list of AI coding assistants and how each runs within Defra-approved terms, the review process for generated code, and disclosure in pull requests or delivery reports
Automated check
Manual
Phases
Alpha, Beta, Live
Led by
Delivery manager, Developer
ShouldGR-AI-08DraftArtificial intelligence

Give agents the least privilege they need

AI agents act under their own identity, with access only to the tools, data and actions their task needs, and never with a person's full permissions.

Evidence
List of each agent's tools and permissions, granted to the agent's own identity and reviewed
Automated check
Manual
Phases
Alpha, Beta, Live
Led by
Technical architect, Security architect
ShouldGR-AI-09DraftArtificial intelligence

Get human approval for consequential actions

An agent does not take an action with legal, financial or significant effects on people, or one that cannot easily be undone, without approval from an accountable person.

Evidence
Design showing which agent actions need human approval, and tests proving they cannot happen without it
Automated check
Manual
Phases
Alpha, Beta, Live
Led by
Service designer, Technical architect
ShouldGR-AI-10DraftArtificial intelligence

Keep an audit trail of what agents do

Record what each agent was asked, what it read, which tools it called with what inputs, who approved what, and the outcome - and send security-relevant events to security monitoring.

Evidence
Audit records of agent inputs, tool calls, approvals and outcomes, sent to security monitoring
Automated check
Manual
Phases
Beta, Live
Led by
Developer, Security architect
ShouldGR-AI-11DraftArtificial intelligence

Defend agents against prompt injection

Treat everything an agent reads - documents, emails, web pages, tool results - as untrusted input that may try to change its instructions, and design controls that hold even if it does.

Evidence
Threat model covering prompt injection through every input the agent reads, with tested mitigations
Automated check
Manual
Phases
Alpha, Beta, Live
Led by
Security architect, Developer
ShouldGR-API-01DraftAPIs and integration

API first

Design the API for a capability before (or with) the user interface, so other services and partners can use it.

Evidence
API specification written before or alongside the user interface
Automated check
Manual
Phases
Alpha, Beta
Led by
Technical architect
ShouldGR-API-02DraftAPIs and integration

Describe APIs with open specifications

Synchronous APIs are described with OpenAPI 3, and asynchronous/event interfaces with AsyncAPI, kept in the same repository as the code.

Evidence
OpenAPI 3 or AsyncAPI documents in the service repository that match the running API
Automated check
Guardrail check (tools/guardrail-check): OpenAPI 3 and AsyncAPI documents present and well formed
Phases
Alpha, Beta, Live
Led by
Developer
ShouldGR-API-03DraftAPIs and integration

Follow government API standards

Follow the API technical and data standards: RESTful resources, JSON, HTTPS only, consistent error formats and standard identifiers from the data standards.

Evidence
API design reviewed against the GDS API technical and data standards
Automated check
Manual
Phases
Alpha, Beta, Live
Led by
Developer, Technical architect
ShouldGR-API-04DraftAPIs and integration

Version and deprecate deliberately

Breaking changes are versioned, consumers are told in advance, and old versions have a published retirement date.

Evidence
Published versioning policy, deprecation notices sent to consumers and retirement dates for old versions
Automated check
Manual
Phases
Beta, Live
Led by
Technical architect, Product manager
ShouldGR-API-05DraftAPIs and integration

No integration through shared databases

Services do not read or write another service's database directly. Integrate through APIs, events or governed data products.

Evidence
Container diagram showing integration only through APIs, events or governed data products
Automated check
Manual
Phases
Alpha, Beta, Live
Led by
Technical architect
ShouldGR-API-06DraftAPIs and integration

Use events for change notifications

Use asynchronous messages or events when other services need to react to something that happened (an application submitted, a permit issued), rather than polling.

Evidence
Event and message definitions described in AsyncAPI
Automated check
Manual
Phases
Alpha, Beta
Led by
Technical architect, Developer
MustGR-API-07DraftAPIs and integration

Secure every API

All APIs authenticate callers (OAuth 2.0 / OpenID Connect or mutual TLS), authorise every request, validate input and apply rate limiting. No API is "internal so it's safe".

Evidence
Authentication and authorisation design, rate limits and input validation, covered by security testing
Automated check
Manual
Phases
Alpha, Beta, Live
Led by
Security architect, Developer
ShouldGR-API-08DraftAPIs and integration

Make APIs discoverable

Register APIs in the platform API catalogue and, where they are useful beyond Defra, the government API catalogue.

Evidence
Entry in the platform API catalogue
Automated check
Manual
Phases
Beta, Live
Led by
Technical architect
MustGR-TECH-01DraftChoosing technology

Look for something to reuse first

Before buying or building, check the technology capability catalogue and cross-government components for something that already meets the need.

Evidence
ADR listing the reuse options considered from the technology capability catalogue and cross-government components
Automated check
Manual
Phases
Discovery, Alpha
Led by
Technical architect
ShouldGR-TECH-02DraftChoosing technology

Buy commodity, build differentiating

Buy or use SaaS for commodity needs (email, HR, finance, CRM, document management). Build only where the capability is specific to Defra's mission and no product fits without heavy customisation.

Evidence
Buy or build options appraisal in the ADR or business case
Automated check
Manual
Phases
Discovery, Alpha
Led by
Technical architect, Product manager
ShouldGR-TECH-03DraftChoosing technology

Plan your exit before you enter

Any new product, platform or significant supplier dependency has a documented exit plan covering data export in open formats, contract terms and an estimate of switching cost.

Evidence
Exit plan covering data export in open formats, contract terms and an estimate of switching cost
Automated check
Manual
Phases
Alpha, Beta, Live
Led by
Technical architect, Delivery manager
MustGR-TECH-04DraftChoosing technology

Assess SaaS before you adopt it

SaaS and third-party hosted products are assessed for security, data protection, data location, accessibility and integration before contract.

Evidence
Supplier security assessment, DPIA where personal data is involved, data location, accessibility and single sign-on confirmed before contract
Automated check
Manual
Phases
Discovery, Alpha
Led by
Security architect, Technical architect
ShouldGR-TECH-05DraftChoosing technology

Prefer open standards and portable technology

Choose products and components that use open standards and can be run on more than one provider.

Evidence
ADR noting the open standards used and how portable the choice is
Automated check
Manual
Phases
Alpha
Led by
Technical architect
MustGR-TECH-06DraftChoosing technology

Get spend approval early

Spend that falls under the government digital and technology spend control is discussed with the architecture team before procurement starts.

Evidence
Record of the conversation with the architecture team before procurement started
Automated check
Manual
Phases
Discovery
Led by
Delivery manager, Product manager
ShouldGR-DATA-01DraftData

Every data set has an owner

Each data set a service creates or holds has a named business owner (information asset owner) and is recorded in the information asset register.

Evidence
Information asset register entries with a named owner for each data set
Automated check
Manual
Phases
Alpha, Beta, Live
Led by
Data architect, Product manager
ShouldGR-DATA-02DraftData

Use authoritative sources

Use the authoritative source for shared entities - customers, organisations, land parcels, holdings, locations, species - rather than creating local copies that drift. See Defra on a page.

Evidence
Data flow diagram naming the authoritative source for each shared entity, with refresh arrangements for any copies
Automated check
Manual
Phases
Discovery, Alpha, Beta, Live
Led by
Data architect
ShouldGR-DATA-03DraftData

Use agreed data standards and identifiers

Use the data standards for dates, addresses, locations, identifiers and code lists, so data can be joined across services.

Evidence
Data model that uses the agreed data standards and identifiers
Automated check
Manual
Phases
Alpha, Beta
Led by
Data architect
ShouldGR-DATA-04DraftData

Collect once, share safely

Do not ask users for information Defra already holds. Share data between services through APIs or governed data products, with data sharing agreements where required.

Evidence
Journey design showing users are not asked for information Defra already holds, and data sharing agreements where required
Automated check
Manual
Phases
Alpha, Beta
Led by
Service designer
ShouldGR-DATA-05DraftData

Describe your data

Publish metadata for data sets so they can be found and understood - UK GEMINI for geospatial data and DCAT for other data sets.

Evidence
Published metadata records in UK GEMINI or DCAT
Automated check
Manual
Phases
Beta, Live
Led by
Data architect
MustGR-DATA-06DraftData

Protect personal data by design

Complete a data protection impact assessment (DPIA) before processing personal data, minimise what you collect, and apply retention and deletion automatically.

Evidence
Approved DPIA, and retention and deletion built into the service
Automated check
Manual
Phases
Discovery, Alpha, Beta, Live
Led by
Data architect, Product manager
ShouldGR-DATA-07DraftData

Open by default

Publish non-personal, non-sensitive data as open data under the Open Government Licence, through the Defra Data Services Platform or data.gov.uk.

Evidence
Link to the published open data and its licence
Automated check
Manual
Phases
Beta, Live
Led by
Data architect, Product manager
ShouldGR-DATA-08DraftData

Manage data quality

Define, measure and report data quality using the Government Data Quality Framework, especially for data that feeds payments, regulatory decisions or official statistics.

Evidence
Data quality measures and regular reports
Automated check
Manual
Phases
Beta, Live
Led by
Data architect, Performance analyst
MustGR-DATA-09DraftData

Retain and dispose of records properly

Apply Defra's retention schedules. Records of permanent value are identified for transfer to The National Archives.

Evidence
Retention schedule applied and records of permanent value identified
Automated check
Manual
Phases
Beta, Live
Led by
Data architect
ShouldGR-DATA-10DraftData

Handle research data safely

Collect research data only with informed consent, store recordings and notes only in Defra-approved places, delete them when they are no longer needed, use only Defra-approved research tools, and screen research for a DPIA.

Evidence
Research plan showing consent, where recordings and notes are stored, when they are deleted, the approved tools used and DPIA screening
Automated check
Manual
Phases
Discovery, Alpha, Beta, Live
Led by
User researcher
ShouldGR-DATA-11DraftData

No real personal data in prototypes

Prototypes, research materials and test environments use made-up or anonymised data, never real personal data copied from a live service or spreadsheet.

Evidence
Prototypes and test environments use made-up or anonymised data, never real personal data
Automated check
Manual
Phases
Discovery, Alpha, Beta
Led by
Interaction designer, User researcher, Developer
ShouldGR-DIG-01DraftDigital first and end-to-end services

Challenge paper and manual processes

Do not put a paper or email process online as it is. Find out why each step exists, and remove, automate or redesign it.

Evidence
Discovery findings showing paper, email and manual steps in the current process and how the new design removes or justifies each one
Automated check
Manual
Phases
Discovery, Alpha
Led by
Service designer, User researcher
ShouldGR-DIG-02DraftDigital first and end-to-end services

Design across organisational boundaries

Design the end-to-end service from the user's point of view, even when parts of it are delivered by other Defra organisations or other parts of government.

Evidence
A map of the whole service, including the parts other teams and organisations deliver, and agreed hand-offs between them
Automated check
Manual
Phases
Discovery, Alpha, Beta
Led by
Service designer
ShouldGR-DIG-03DraftDigital first and end-to-end services

Provide assisted digital and offline routes

Make sure people who cannot use the online service, or cannot use it alone, can still get what they need - with help, by phone or on paper - and that those routes lead to the same outcome and data.

Evidence
Assisted digital and offline routes designed and tested with users who need them
Automated check
Manual
Phases
Alpha, Beta, Live
Led by
Service designer, User researcher
ShouldGR-FIELD-01DraftField working and devices

Choose devices that suit the job

Choose devices for field work from research into where and how people work - outdoors, in bad weather, wearing gloves, in the dark - not from what is already on the desk.

Evidence
User research on the working environment, and the device choice recorded in an ADR
Automated check
Manual
Phases
Discovery, Alpha
Led by
User researcher, Service designer
ShouldGR-FIELD-02DraftField working and devices

Design field tools to work offline

Field tools work without a connection: they download what is needed before a visit, save work on the device, and sync safely when back in signal.

Evidence
Field journeys tested with no connection, including sync after reconnecting and conflict handling
Automated check
Manual
Phases
Alpha, Beta, Live
Led by
Interaction designer, Developer
ShouldGR-FIELD-03DraftField working and devices

Manage and secure every device

Devices that hold or access Defra data are enrolled in Defra device management, encrypted, kept patched, protected by a screen lock and able to be wiped remotely if lost.

Evidence
Devices enrolled in Defra device management, with encryption, patching and remote wipe confirmed
Automated check
Manual
Phases
Alpha, Beta, Live
Led by
Security architect
CouldGR-FIELD-04DraftField working and devices

Check connectivity before you design

Check the mobile and broadband coverage where the service will be used before choosing an approach, rather than assuming it.

Evidence
Connectivity in the places the service will be used checked, and the approach recorded
Automated check
Manual
Phases
Discovery, Alpha
Led by
User researcher, Technical architect
MustGR-FE-01DraftFront end and accessibility

Meet WCAG 2.2 AA

Public and staff-facing services meet WCAG 2.2 level AA, are tested with assistive technology and publish an accessibility statement.

Evidence
Accessibility audit, assistive technology testing results and a published accessibility statement
Automated check
Automated accessibility tests such as axe in the pipeline. These find some issues only; manual testing is still needed.
Phases
Alpha, Beta, Live
Led by
Interaction designer, Developer
MustGR-FE-02DraftFront end and accessibility

Use the GOV.UK Design System

Public-facing services use GOV.UK Frontend and patterns. Staff-facing services should use them too.

Evidence
The service uses GOV.UK Frontend and design decisions record where it departs from the patterns
Automated check
Manual
Phases
Alpha, Beta, Live
Led by
Interaction designer, Developer
ShouldGR-FE-03DraftFront end and accessibility

Progressive enhancement

Core journeys work without JavaScript, and are server-rendered. Use JavaScript to enhance, not to make things work.

Evidence
Core journeys tested with JavaScript turned off
Automated check
Manual
Phases
Alpha, Beta
Led by
Developer, Interaction designer
ShouldGR-FE-04DraftFront end and accessibility

Consider forms platforms first

For form-based services, consider the forms options under Customer Service before building a bespoke front end.

Evidence
ADR noting whether the forms capability was considered
Automated check
Manual
Phases
Discovery, Alpha
Led by
Service designer, Technical architect
ShouldGR-FE-05DraftFront end and accessibility

Design for low bandwidth and rural users

Many Defra users - farmers, land managers, field staff - work in places with poor connectivity. Keep pages light, support saving progress, and consider offline working for field tools.

Evidence
Page weight budget, save-progress design and testing on slow connections
Automated check
Manual
Phases
Alpha, Beta
Led by
Service designer, User researcher
MustGR-FE-06DraftFront end and accessibility

Support Welsh where required

Services used in Wales meet the Welsh Language Standards where they apply. Design for translation from the start.

Evidence
Assessment of whether the Welsh Language Standards apply and translated content where they do
Automated check
Manual
Phases
Alpha, Beta, Live
Led by
Content designer
ShouldGR-FE-07DraftFront end and accessibility

Tell users what is happening when things fail or are slow

When a service is slow, a dependency fails or something is still being processed, users see a clear message saying what has happened, whether their work is saved, and what to do next - not a generic error or a page that seems to hang.

Evidence
Designed and tested content for each way the service can fail or slow down, and the front end showing it
Automated check
Manual
Phases
Alpha, Beta, Live
Led by
Content designer, Developer, Interaction designer
MustGR-HOST-01DraftHosting and platforms

Use Defra's strategic delivery platform by default

New digital services are hosted on the Defra Core Delivery Platform (CDP) unless an exception has been agreed.

Evidence
The service runs on the Core Delivery Platform, or an approved exception
Automated check
Manual
Phases
Discovery, Alpha, Beta, Live
Led by
Technical architect
ShouldGR-HOST-02DraftHosting and platforms

Public cloud first

Where a service cannot use a strategic platform, it is hosted in a Defra-managed public cloud tenancy. New on-premises hosting is not permitted.

Evidence
Hosting design showing a Defra-managed public cloud tenancy
Automated check
Manual
Phases
Alpha, Beta, Live
Led by
Technical architect
ShouldGR-HOST-03DraftHosting and platforms

Everything as code

Infrastructure, configuration, pipelines and policies are defined as code, version-controlled and deployed through automated pipelines. No manual changes to production.

Evidence
Infrastructure, configuration and pipeline code in the repository, and drift detection results
Automated check
Manual
Phases
Beta, Live
Led by
Developer
ShouldGR-HOST-04DraftHosting and platforms

Use managed services before self-managed

Prefer managed cloud services (databases, queues, storage) over running your own on virtual machines.

Evidence
Hosting design listing the managed services used
Automated check
Manual
Phases
Alpha, Beta
Led by
Technical architect, Developer
ShouldGR-HOST-05DraftHosting and platforms

Consistent, disposable environments

Have at least development, test and production environments, created from the same code, with production data never copied to lower environments unless anonymised.

Evidence
Environments created from the same code, and how lower environments avoid real personal data
Automated check
Manual
Phases
Alpha, Beta, Live
Led by
Developer
ShouldGR-HOST-06DraftHosting and platforms

Host data in the UK

Data classified OFFICIAL is held in UK regions unless an assessed and approved exception exists.

Evidence
Data location confirmed for every data store and backup
Automated check
Manual
Phases
Alpha, Beta, Live
Led by
Technical architect, Security architect
ShouldGR-HOST-07DraftHosting and platforms

Design for the resilience the service needs

Agree recovery time and recovery point objectives with the service owner, design to them across availability zones, and test recovery at least once a year.

Evidence
Agreed recovery time and recovery point objectives, a multi-zone design and the date of the last recovery test
Automated check
Manual
Phases
Alpha, Beta, Live
Led by
Technical architect, Product manager
MustGR-IAM-01DraftIdentity and access

Use the strategic customer identity services

Services for citizens, farmers and businesses use Defra Customer Identity (Defra ID), which uses GOV.UK One Login and Government Gateway as identity providers, for authentication. Services do not build their own sign-in. See Defra Customer Identity in the Defra Digital Service Manual.

Evidence
Integration with Defra Customer Identity and the agreed level of identity assurance
Automated check
Manual
Phases
Discovery, Alpha, Beta, Live
Led by
Technical architect, Service designer
MustGR-IAM-02DraftIdentity and access

Staff sign in with Microsoft Entra ID

Staff-facing services and products, including SaaS, use single sign-on through Microsoft Entra ID with multi-factor authentication. No local staff accounts.

Evidence
Single sign-on through Microsoft Entra ID with multi-factor authentication and no local staff accounts
Automated check
Manual
Phases
Beta, Live
Led by
Technical architect
MustGR-IAM-03DraftIdentity and access

Authorise on least privilege

Users, services and pipelines get only the permissions they need, granted through roles or groups, and reviewed regularly.

Evidence
Role and group model and a record of access reviews
Automated check
Manual
Phases
Beta, Live
Led by
Security architect, Developer
ShouldGR-IAM-04DraftIdentity and access

Separate authentication from authorisation

Use the identity provider to establish who someone is; keep business authorisation rules (for example "can act for this holding") explicit, testable and in the right service.

Evidence
Authorisation rules written down and covered by automated tests
Automated check
Manual
Phases
Alpha, Beta
Led by
Developer, Technical architect
MustGR-IAM-05DraftIdentity and access

No secrets in code

Secrets, keys and credentials are held in a managed secrets store, rotated, and never committed to source control. Use workload identity in preference to long-lived keys.

Evidence
Secrets held in a managed store with rotation and secret scanning enabled
Automated check
GitHub secret scanning with push protection
Phases
Alpha, Beta, Live
Led by
Developer
MustGR-IAM-06DraftIdentity and access

Privileged access is controlled and audited

Production and administrative access is just-in-time, uses phishing-resistant MFA, and is logged to the security operations centre.

Evidence
Just-in-time privileged access with phishing-resistant MFA and logs reaching the security operations centre
Automated check
Manual
Phases
Beta, Live
Led by
Security architect
ShouldGR-OPS-01DraftObservability and operations

Use the platform's observability tooling

Send structured logs, metrics and traces to the platform's observability tooling, and security events to the security operations centre.

Evidence
Dashboards and alerts in the platform's observability tooling and security events reaching the security operations centre
Automated check
Manual
Phases
Beta, Live
Led by
Developer
ShouldGR-OPS-02DraftObservability and operations

Log in a structured, safe way

Use structured (JSON) logs with correlation identifiers across service boundaries. Never log secrets, tokens or unnecessary personal data.

Evidence
Sample logs showing structured fields and correlation identifiers and no secrets
Automated check
Manual
Phases
Beta, Live
Led by
Developer
ShouldGR-OPS-03DraftObservability and operations

Define and measure service levels

Agree service level objectives for availability, latency and correctness with the service owner, monitor them, and alert on what matters to users rather than on every metric.

Evidence
Agreed service level objectives with monitoring and alerts
Automated check
Manual
Phases
Beta, Live
Led by
Product manager, Performance analyst, Technical architect
ShouldGR-OPS-04DraftObservability and operations

Health checks and graceful degradation

Expose health endpoints, set timeouts and retries on dependencies, and degrade gracefully (for example save progress and tell the user) when a dependency fails.

Evidence
Health endpoints, timeout and retry settings, and a design for when dependencies fail
Automated check
Manual
Phases
Beta, Live
Led by
Developer, Interaction designer
MustGR-OPS-05DraftObservability and operations

Be ready for live before you go live

Before public beta, agree the support model, on-call arrangements, runbooks, incident process and who owns the service in live. Register the service in the service catalogue.

Evidence
Support model, on-call arrangements, runbooks, incident process, named live owner and service catalogue entry
Automated check
Manual
Phases
Beta, Live
Led by
Delivery manager, Product manager
ShouldGR-OPS-06DraftObservability and operations

Learn from incidents

Hold blameless post-incident reviews for significant incidents and share the lessons in the open where appropriate.

Evidence
Post-incident reviews and the actions taken
Automated check
Manual
Phases
Live
Led by
Delivery manager
ShouldGR-OPS-07DraftObservability and operations

Measure performance and cost

Publish the mandatory key performance indicators and tag cloud resources so cost can be attributed to the service and business capability.

Evidence
Published key performance indicators and cost tags on cloud resources
Automated check
Manual
Phases
Beta, Live
Led by
Performance analyst, Product manager
MustGR-OPEN-01DraftOpen source and working in the open

Code in the open

New source code is public from the start, in a Defra GitHub organisation, unless there is a recorded reason to keep a specific repository private (for example fraud rules or unannounced policy).

Evidence
Public repository in a Defra GitHub organisation, or a recorded reason for keeping it private
Automated check
Manual
Phases
Alpha, Beta, Live
Led by
Developer, Delivery manager
ShouldGR-OPEN-02DraftOpen source and working in the open

Licence clearly

Code is released under the Open Government Licence or the MIT licence, with a LICENCE file in every repository.

Evidence
LICENCE file with the Open Government Licence or MIT licence in every repository
Automated check
Guardrail check (tools/guardrail-check): LICENCE file with the Open Government Licence or MIT
Phases
Alpha, Beta, Live
Led by
Developer
ShouldGR-OPEN-03DraftOpen source and working in the open

Publish safely

Enable secret scanning and push protection on every repository. Keep secrets, credentials and sensitive configuration out of code.

Evidence
Secret scanning and push protection enabled on every repository
Automated check
Guardrail check (tools/guardrail-check): secret scanning and push protection turned on, with a token that can read security settings
Phases
Alpha, Beta, Live
Led by
Developer, Security architect
ShouldGR-OPEN-04DraftOpen source and working in the open

Reuse and contribute back

Use and improve existing open source and Defra components rather than forking or rewriting. Contribute fixes back upstream.

Evidence
Reuse and upstream contributions noted in ADRs and pull requests
Automated check
Manual
Phases
Alpha, Beta, Live
Led by
Developer
CouldGR-OPEN-05DraftOpen source and working in the open

Blog and show the thing

Share what you learn on the Defra Digital blog, at show and tells, and in this repository.

Evidence
Blog posts, show and tells or contributions to this site
Automated check
Manual
Phases
Discovery, Alpha, Beta, Live
Led by
Delivery manager
ShouldGR-PROD-01DraftProducts and platforms

Fund and run products, not projects

Build and run digital services as products, owned by a long-lived team that keeps improving them, rather than as projects that end at go-live.

Evidence
A named, long-lived team responsible for the product, with a roadmap beyond the current funding period
Automated check
Manual
Phases
Alpha, Beta, Live
Led by
Product manager
ShouldGR-PROD-02DraftProducts and platforms

Name the product owner and service owner

Every product has a named product owner, and every service a named service owner, who are accountable for it throughout its life.

Evidence
Named product owner and service owner, recorded in the service catalogue
Automated check
Manual
Phases
Discovery, Alpha, Beta, Live
Led by
Product manager, Delivery manager
ShouldGR-PROD-03DraftProducts and platforms

Contribute to platforms rather than working around them

When a shared platform does not meet a need, raise it with the platform team and contribute to fixing it, rather than building a local workaround.

Evidence
Requests and contributions raised with platform teams, and ADRs where the team worked around a platform
Automated check
Manual
Phases
Alpha, Beta, Live
Led by
Technical architect, Product manager
ShouldGR-PROD-04DraftProducts and platforms

Plan for the end of a product's life

Know where each product is in its lifecycle - growing, stable, being replaced or retiring - and plan its retirement as deliberately as its launch.

Evidence
Product lifecycle stage recorded, with a retirement plan for products being replaced
Automated check
Manual
Phases
Live
Led by
Product manager
MustGR-SEC-01DraftSecurity

Follow Secure by Design

Every new service and significant change follows the Secure by Design activities, with a named risk owner, from discovery onward.

Evidence
Named risk owner and the Secure by Design activities completed for the phase
Automated check
Manual
Phases
Discovery, Alpha, Beta, Live
Led by
Security architect
MustGR-SEC-02DraftSecurity

Keep a current threat model

Each service has a threat model, created by the team in alpha and revisited at every significant change and at least annually.

Evidence
Current, dated threat model, reviewed at the last significant change and at least annually
Automated check
Manual
Phases
Alpha, Beta, Live
Led by
Security architect, Developer
MustGR-SEC-03DraftSecurity

Classify information

Identify the government security classification and data types the service handles, and design controls to match.

Evidence
Security classification and data types recorded with the controls that match them
Automated check
Manual
Phases
Discovery, Alpha
Led by
Security architect, Data architect
MustGR-SEC-04DraftSecurity

Encrypt in transit and at rest

Use TLS 1.2 or higher for all traffic, internal and external, and encrypt data at rest using platform-managed or customer-managed keys.

Evidence
TLS configuration and encryption at rest settings for every data store
Automated check
Manual
Phases
Beta, Live
Led by
Developer, Security architect
MustGR-SEC-05DraftSecurity

Scan continuously and fix quickly

Run static analysis, dependency, container and infrastructure scanning in the pipeline. Fix critical vulnerabilities within 14 days and high within 30 days, or record a risk decision.

Evidence
Pipeline scanning results and the time taken to fix critical and high vulnerabilities
Automated check
Static analysis, dependency, container and infrastructure scanning in the pipeline
Phases
Beta, Live
Led by
Developer
MustGR-SEC-06DraftSecurity

Test before go-live and after major change

Commission an independent IT health check (penetration test) proportionate to risk before go-live and after significant change, and track remediation.

Evidence
IT health check report and remediation tracker
Automated check
Manual
Phases
Beta, Live
Led by
Security architect, Delivery manager
MustGR-SEC-07DraftSecurity

Log for detection and response

Send security-relevant events (authentication, authorisation failures, administrative actions, data exports) to the security operations centre. See GR-OPS-01.

Evidence
Security-relevant events reaching the security operations centre
Automated check
Manual
Phases
Beta, Live
Led by
Developer, Security architect
ShouldGR-SEC-08DraftSecurity

Protect the supply chain

Assess suppliers and third-party products for security before use, pin and verify dependencies, and know what is in your software (keep a software bill of materials).

Evidence
Supplier security assessments, pinned dependencies and a software bill of materials
Automated check
Dependency review and software bill of materials generation in the pipeline
Phases
Alpha, Beta, Live
Led by
Security architect, Developer
MustGR-SEC-09DraftSecurity

Manage risk explicitly

Where a control cannot be met, record the risk and get it accepted by the right owner through the security exception process. Accepted risks are time-limited.

Evidence
Risk register entries with an owner and an expiry date for every accepted risk
Automated check
Manual
Phases
Alpha, Beta, Live
Led by
Security architect, Product manager
ShouldGR-DEV-01DraftSoftware development

Use the supported languages and frameworks

Use Defra's approved technologies and languages for new services so that skills, libraries and support are shared.

Evidence
ADR recording the reason wherever the service uses a different stack
Automated check
Manual
Phases
Alpha
Led by
Technical architect, Developer
MustGR-DEV-02DraftSoftware development

All code in Defra source control

All source code, including infrastructure and pipeline code written by suppliers, lives in a Defra-owned GitHub organisation from day one.

Evidence
All source code in a Defra-owned GitHub organisation from the first commit
Automated check
Manual
Phases
Alpha, Beta, Live
Led by
Developer, Delivery manager
ShouldGR-DEV-03DraftSoftware development

Protect the main branch

Main branches are protected: changes arrive through pull requests with at least one review and passing automated checks.

Evidence
Branch protection on the main branch requiring a review and passing checks
Automated check
Guardrail check (tools/guardrail-check): default branch protected by branch protection or a ruleset
Phases
Alpha, Beta, Live
Led by
Developer
ShouldGR-DEV-04DraftSoftware development

Continuous integration and delivery

Every change is built, tested, scanned and deployed by an automated pipeline. Releases to production are small, frequent and reversible.

Evidence
Pipeline definition in the repository and deployment history
Automated check
Manual
Phases
Beta, Live
Led by
Developer
ShouldGR-DEV-05DraftSoftware development

Automated testing at the right levels

Use a balanced set of automated tests - unit, integration/contract, end-to-end journey, accessibility, performance and security - run in the pipeline.

Evidence
Test results from the pipeline at each level
Automated check
Manual
Phases
Alpha, Beta, Live
Led by
Developer
ShouldGR-DEV-06DraftSoftware development

Manage dependencies actively

Use automated dependency updates and software composition analysis, and keep runtimes on supported versions.

Evidence
Dependabot or Renovate configuration and runtimes on supported versions
Automated check
Guardrail check (tools/guardrail-check): Dependabot or Renovate configured
Phases
Beta, Live
Led by
Developer
ShouldGR-DEV-07DraftSoftware development

Follow shared coding standards

Use automated linting and formatting, and follow the Defra software development standards, so code looks and behaves consistently across teams.

Evidence
Linting and formatting checks in the pipeline
Automated check
Lint and format checks in the pipeline
Phases
Alpha, Beta, Live
Led by
Developer
ShouldGR-DEV-08DraftSoftware development

Document as you go

Each repository has a README explaining what it does, how to run it locally, how to test it and how to deploy it, and links to its ADRs.

Evidence
README explaining what the service does and how to run, test and deploy it, with links to its ADRs
Automated check
Guardrail check (tools/guardrail-check): README sections on running, testing and deploying, and a link to ADRs
Phases
Alpha, Beta, Live
Led by
Developer
ShouldGR-DEV-09DraftSoftware development

Record significant decisions as ADRs

Record significant architecture decisions as architecture decision records (ADRs), kept with the code or linked from the repository's README.

Evidence
ADR log in the repository or linked from its README
Automated check
Guardrail check (tools/guardrail-check): ADRs in docs/adr
Phases
Discovery, Alpha, Beta, Live
Led by
Technical architect
ShouldGR-SUS-01DraftSustainability

Consider sustainability in design decisions

Include environmental impact as a factor in ADRs for hosting, architecture and technology choices.

Evidence
Environmental impact recorded in ADRs for hosting and technology choices
Automated check
Manual
Phases
Discovery, Alpha
Led by
Technical architect
ShouldGR-SUS-02DraftSustainability

Right-size and switch off

Use autoscaling, scale non-production environments down out of hours, and delete unused resources.

Evidence
Autoscaling and out-of-hours schedules for non-production environments
Automated check
Manual
Phases
Beta, Live
Led by
Developer
CouldGR-SUS-03DraftSustainability

Choose lower-carbon regions and services

Where data rules allow, prefer cloud regions and services with lower carbon intensity, and use providers' carbon reporting.

Evidence
Region and service choice recorded with its carbon intensity
Automated check
Manual
Phases
Alpha
Led by
Technical architect
ShouldGR-SUS-04DraftSustainability

Keep data and pages lean

Store only the data you need, for as long as you need it, and keep page weight low - which also helps users on slow connections (GR-FE-05).

Evidence
Data retention settings and page weight measurements
Automated check
Manual
Phases
Alpha, Beta, Live
Led by
Developer, Interaction designer
CouldGR-SUS-05DraftSustainability

Measure and report

Track the carbon footprint of your service using cloud provider tooling and report it alongside cost.

Evidence
Carbon footprint reported alongside cost
Automated check
Manual
Phases
Live
Led by
Performance analyst, Technical architect

. - **Build hooks check and generate.** Small Python scripts inhooks/read the YAML and front matter, check it and generate the guardrail library, traceability tables, open questions list, draft banners and abbreviation tooltips. If the data is wrong, the build fails with a message saying what to fix. - **Machine-readable outputs.** Every build publishesguardrails.jsonandnfrs.json`. Every release also gets a version tag and a PDF of every guardrail, so contracts can cite a fixed version.

flowchart LR
    accTitle: How a change becomes the published site
    accDescr: Pages in the docs folder, data in YAML files and the site settings in mkdocs.yml go into the build. The build hooks and checks validate ids and fields, generate tables and test links and accessibility. If the data is invalid the build fails and the pull request is blocked. Otherwise the build publishes the website, the guardrails and NFR JSON files and, when a version is released, a release tag and a PDF of every guardrail.
    PAGES["Pages in docs/"] --> BUILD["Build hooks and checks"]
    DATA["Data in YAML"] --> BUILD
    CONF["mkdocs.yml"] --> BUILD
    BUILD --> SITE["Website"]
    BUILD --> JSON["guardrails.json and nfrs.json"]
    BUILD --> REL["Release tag and PDF"]
    BUILD -->|"invalid data"| FAIL["Build fails, pull request blocked"]

You change words in docs/ and values in the YAML files. You almost never need to touch hooks/, overrides/ or the stylesheets.

Rules every change follows

Most of these are enforced by the build, so breaking one fails the pull request rather than reaching the site.

Rule What it means in practice Checked by
Ids are permanent Never renumber, rename, reuse or delete a guardrail, principle, doctrine or NFR id, because contracts cite them. To retire one, set status: deprecated and replaced_by:. A new one takes the next free number in its area and starts as status: draft. Build and tests
Never guess a Defra fact Names, mailboxes, web addresses, lead times, approvals and owners come from someone who knows. If you do not know, add a "To be confirmed" box. It appears on the open questions page automatically. Review
Musts only where required A Must needs a legal, policy or security reason, evidence for each phase, review by the Technical Design Authority and approval by the Technology Governance Board. Use Should by default. Tests limit the number of Musts
Link, do not repeat Step-by-step tasks, contacts and team processes belong in the Defra Digital Service Manual. Guardrails, decisions and evidence belong here. See where things live. Matching links test
GOV.UK style Plain English, active voice, sentence case headings. Lead with what the team must do and explain why. Expand abbreviations the first time you use them. See content style. Prose checks (warnings)
Accessible WCAG 2.2 AA in light and dark mode. Every diagram needs accTitle and accDescr. Link text says where the link goes. Accessibility test and tests
Public repository No secrets, internal hostnames, IP addresses, personal data, commercially sensitive detail or detailed security weaknesses. Review
Record every change Add a line under ## [Unreleased] in CHANGELOG.md and update what's new. Review

Edit the YAML or front matter, never the generated output. Keep each pull request to one change so it can be reviewed quickly.

Which file to edit

The common tasks on the contribute page give the exact fields and templates for each of these.

To Edit Watch out for
Fix wording on any page The page in docs/, or select Edit this page on the site Nothing else - a small pull request is fine
Reword a guardrail Its section in docs/guardrails/ Keep the heading shape ## GR-HOST-01 Title {#gr-host-01} and the badge at the start of the first line. Changing what a Must asks for needs the must-change label.
Add a guardrail Heading, badge, why and how to meet it in the page, and a guardrails: entry in the front matter Next free id, status: draft, lead_roles, and for a Must evidence and evidence_by_phase for every phase
Retire a guardrail Its metadata: status: deprecated and replaced_by: Leave the section on the page - never delete it
Change who a page applies to applicability: in the page front matter Write tbc until it is agreed
Change the doctrine or principles docs/principles/doctrine.md or docs/principles/architecture-principles.md Keep the heading shapes. Changes need Technology Governance Board approval.
Add a pattern Copy a page in docs/patterns/, set its pattern: front matter and add it to the navigation Keep every section in order and the <!-- patterns: --> markers
Change an NFR or service tier nfrs/catalogue.yaml or nfrs/service-tiers.yaml Comments at the top of each file explain every field
Change the lifecycle, platforms or roles The files in delivery/ Write tbc for a platform detail that is not known yet
Change the capability model The files in capabilities/ The map, catalogue and mapping matrix are generated from them
Record an approval or exception The files in registers/ Ids, dates and guardrail ids are checked
Answer an open question Replace the "To be confirmed" box with the fact Close the open-question issue from the pull request
Mark a page as draft status: draft in its front matter Remove it once the content is agreed
Mark a whole section as a prototype Add it under extra.prototype in mkdocs.yml, with a note Every page in the section shows a prototype banner. Remove the entry once the section has been tested.
Add an abbreviation includes/abbreviations.md Still write it in full the first time it is used on each page
Add a page A new Markdown file in the right docs/ folder Add it to nav in mkdocs.yml

To change a Must, label the pull request must-change and do not merge it until the Technical Design Authority has reviewed it and the Technology Governance Board has approved it. Then record the decision in registers/approvals.yaml. MAINTAINERS.md has the full route.

From change to published site

  1. Make the change on a branch, or select Edit this page, which makes a branch for you. Add a line to CHANGELOG.md under ## [Unreleased].
  2. Check it on your computer if you can: install the tools, run mkdocs serve and open the page. Before you push, run pytest and mkdocs build --strict. The checks table lists every command.
  3. Open a pull request. The template asks what changed and why. The checks run automatically and the right reviewer is asked for a review.
  4. Review and merge. Every pull request is triaged within 2 weeks. Changes to a Must wait for the Technical Design Authority and Technology Governance Board.
  5. Publish. Merging to main publishes the site within a few minutes. A maintainer makes a release by giving the Unreleased changes a version number. The release workflow then tags it and attaches the guardrails PDF.

If you cannot see your change on the site, your browser may be showing an old copy. Reload the page while holding Shift.

If a check fails

Open the failed check and read the last lines. The message names the file and what to fix.

The message says Fix
has anchor ..., expected ... Make the {#gr-...} anchor the id in lower case
has no Principle/Must/Should/Could badge Put the badge at the start of the first line under the heading
has no metadata under 'guardrails:' Add the id to the page's front matter
metadata for ..., which has no heading The id in the front matter and the id in the heading do not match
a Must with no evidence Add evidence, and an evidence_by_phase entry for each phase
is replaced by ..., which does not exist Correct replaced_by
add 'applicability:' Add applicability: tbc to the page's front matter
an email address that is not allowed Use an agreed mailbox. A maintainer adds new ones to the allowed list in the tests.
a diagram without accTitle or accDescr Add both lines to the diagram
a link or anchor that was not found Link to the .md file with a relative path, and check the heading exists

Who to ask

Ask the content designer about wording and style, the owner named in a guardrail's metadata about that guardrail, and the lead maintainer about the build and releases. MAINTAINERS.md lists the roles.

To be confirmed

TODO: the names of the content designer, guardrail area owners and lead maintainer.