diff --git a/docs/explanations/cloud-platform/aws.md b/docs/explanations/cloud-platform/aws.md
index 59a163682c57fc101c3460867af699a45dd38a0b..4b0acbba93fdd245e0a2d1bd01504d7fccac48d6 100644
--- a/docs/explanations/cloud-platform/aws.md
+++ b/docs/explanations/cloud-platform/aws.md
@@ -4,7 +4,7 @@ title: Integrating AWS with our infrastructure
# Integrating AWS with our infrastructure
This guide discusses in greater depth the rationale and design behind our AWS integration. There is
-a more [how-to focused guide](../howtos/get-started-with-aws.md) if all you want to do is add AWS
+a more [how-to focused guide](site:howtos/aws/get-started-with-aws.md) if all you want to do is add AWS
integration to your product.
## Why we would use AWS
@@ -67,7 +67,7 @@ model. The model we use with Google Cloud is explained [in a separate
guide](./google-cloud-permissions-model.md) but in brief:
- Real Person "admin" users sign in to Google with [gcloud admin
- accounts](../howtos/create-gcloudadmin-account.md) which are managed by the
+ accounts](site:howtos/cloud-platform/create-gcloudadmin-account.md) which are managed by the
[gcp-workspace-management](https://gitlab.developers.cam.ac.uk/uis/devops/infra/gcp-workspace-management)
terraform configuration.
- These accounts appear in "editor" or "deploy" groups for a product. For example,
@@ -94,7 +94,7 @@ deployments in similar ways to one another. As we create one Google *project* fo
we also create an AWS *account* for each environment.
A design aim was that this be manual for the moment but amenable to automation via terraform at a
-later date. The [how-to guide on creating AWS accounts](../howtos/create-aws-accounts.md) covers the
+later date. The [how-to guide on creating AWS accounts](site:howtos/aws/create-aws-accounts.md) covers the
process in depth.
## User and Role management within AWS
@@ -130,7 +130,7 @@ You can see an example of this if you run the `gcloud auth print-identity-token`
the result into [https://jwt.ms/](https://jwt.ms/).
<figure markdown>
-
+
<figcaption markdown>
An example Google identity token being parsed and verified by [https://jwt.ms](https://jwt.ms).
</figcaption>
@@ -150,7 +150,7 @@ claims.
audience match the URL of the service. This means that one cannot reuse a token created for one
service to authenticate to another.
-In the [AWS how-to guide](../howtos/get-started-with-aws.md) we cover the process in detail but, in
+In the [AWS how-to guide](site:howtos/aws/get-started-with-aws.md) we cover the process in detail but, in
brief, AWS lets us use these sort of tokens for authenticating as IAM Roles by setting something
known as a *trust policy*. You specify the expected audience, issuer and subject of an identity
token and AWS will take care of performing the necessary steps to verify the token. AWS calls this
@@ -181,7 +181,7 @@ match.
The primary reason to restrict the TerraformDeploy role's permissions is to guard against
inadvertent actions and *not* to guard against malicious actions. The default policy in the [getting
-started how-to guide](../howtos/get-started-with-aws.md) includes the `iam:*` permission for
+started how-to guide](site:howtos/aws/get-started-with-aws.md) includes the `iam:*` permission for
brevity. This permission is sufficient to configure the AWS console user role but may also be
considered overly broad in some circumstances. For example, this permission would trivially enable
the TerraformDeploy role to add additional permissions to itself.
@@ -223,7 +223,7 @@ data "google_service_account_id_token" "aws_terraform_deploy" {
!!! note
If you're interested in how the various locals used here are defined, look at the full [AWS
- how-to guide](../howtos/get-started-with-aws.md).
+ how-to guide](site:howtos/aws/get-started-with-aws.md).
The token is then used with the AWS terraform provider to assume the TerraformDeploy role:
@@ -251,7 +251,7 @@ provider "aws" {
The corresponding "Admin" IAM Role and associated trust policy is added by terraform itself. The IAM
Role is granted full permissions on the AWS account which include access to the AWS console. See the
-[AWS how-to guide](../howtos/get-started-with-aws.md) for full details.
+[AWS how-to guide](site:howtos/aws/get-started-with-aws.md) for full details.
The Admin IAM Role is configured to trust identity tokens for a matching Google-side "AWS admin"
service account. A Google Cloud IAM policy is added to allow members of the "editor" group to
@@ -276,11 +276,11 @@ AWS](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_enable-
However, that is tedious in the extreme and so we have written a tool called
[aws-helper](https://gitlab.developers.cam.ac.uk/uis/devops/tools/aws-helper) which automates this
little dance. Information on how to use the tool can be found in a [dedicated
-guide](../howtos/access-aws-console.md).
+guide](site:howtos/aws/access-aws-console.md).
As a nice side-effect, with a little more effort the aws-helper tool can also act as a [credential
helper](https://docs.aws.amazon.com/cli/v1/userguide/cli-configure-sourcing-external.html) for the
-`aws` CLI tool. This is covered in a [separate how-to guide](../howtos/use-aws-cli.md).
+`aws` CLI tool. This is covered in a [separate how-to guide](site:howtos/aws/use-aws-cli.md).
## Summary
@@ -307,7 +307,7 @@ products.
## See also
-- [How to add AWS to an existing product](../howtos/get-started-with-aws.md)
-- [How to access the AWS console](../howtos/access-aws-console.md)
-- [How to audit access to the AWS console](../howtos/audit-aws-console-access.md)
-- [How to use the `aws` CLI tool](../howtos/use-aws-cli.md)
+- [How to add AWS to an existing product](site:howtos/aws/get-started-with-aws.md)
+- [How to access the AWS console](site:howtos/aws/access-aws-console.md)
+- [How to audit access to the AWS console](site:howtos/aws/audit-aws-console-access.md)
+- [How to use the `aws` CLI tool](site:howtos/aws/use-aws-cli.md)
diff --git a/docs/explanations/cloud-platform/azure-and-entra-id-apps.md b/docs/explanations/cloud-platform/azure-and-entra-id-apps.md
index 12f0815f154ee7222d8ff797a66a03a7dd9ccfdb..9a81fa1e73aae8a3530759504621219583edc344 100644
--- a/docs/explanations/cloud-platform/azure-and-entra-id-apps.md
+++ b/docs/explanations/cloud-platform/azure-and-entra-id-apps.md
@@ -37,7 +37,7 @@ The two products most relevant to this guide are:
* authentication and authorisation via Entra ID-issued access tokens.
**There is no such thing as "Azure API Gateway".** Using terms like "API Gateway" risks confusion
-with the [API Gateway service](../services/api-gateway.md).
+with the [API Gateway service](site:services/api-gateway.md).
## The three hats of an Application Registration
@@ -193,5 +193,5 @@ In this explainer we covered:
## See also
-* [Useful URLs and IDs for dealing with Entra ID Applications](../reference/entra-id.md)
-* [How to add sign in to a web application](../howtos/add-sso-sign-in.md)
+* [Useful URLs and IDs for dealing with Entra ID Applications](site:reference/misc/entra-id.md)
+* [How to add sign in to a web application](site:howtos/entra-azure/add-sso-sign-in.md)
diff --git a/docs/explanations/cloud-platform/gcloudadmin-accounts.md b/docs/explanations/cloud-platform/gcloudadmin-accounts.md
index 5339fd1de26ee70fdc0bffbd415b9b4e4ff542ab..efec74da54bd548f43ee7b1da342f198224e777e 100644
--- a/docs/explanations/cloud-platform/gcloudadmin-accounts.md
+++ b/docs/explanations/cloud-platform/gcloudadmin-accounts.md
@@ -1,6 +1,6 @@
# Google Cloud admin accounts
-As noted in the [checklist for products](../howtos/check-product-configuration.md), development team
+As noted in the [checklist for products](site:howtos/products/check-product-configuration.md), development team
members who need to administer, deploy or examine Google Cloud resources need to be listed in our
[team data
file](https://gitlab.developers.cam.ac.uk/uis/devops/infra/terraform/team-data/-/blob/master/team_data.json)
@@ -43,4 +43,4 @@ DO:
## More information
-* [How to create a Google Cloud admin account](../howtos/create-gcloudadmin-account.md).
+* [How to create a Google Cloud admin account](site:howtos/cloud-platform/create-gcloudadmin-account.md).
diff --git a/docs/explanations/cloud-platform/gcp-budgets-alerts.md b/docs/explanations/cloud-platform/gcp-budgets-alerts.md
index f47aebcfd92a4c5854db12f4ec6dd592bf2f257d..7d810074e314f8b9eb5030e223de6bef2a4f94de 100644
--- a/docs/explanations/cloud-platform/gcp-budgets-alerts.md
+++ b/docs/explanations/cloud-platform/gcp-budgets-alerts.md
@@ -7,7 +7,7 @@ title: Budgets and Alerts
This document explains how billing budgets and alerts are configured for our
Google Cloud Platform (GCP) products. For information on how to react to
triggered alerts see [How to respond to billing
-alerts](../howtos/respond-to-billing-alerts.md).
+alerts](site:howtos/cloud-platform/respond-to-billing-alerts.md).
## Introduction
@@ -56,7 +56,7 @@ The product factory configures two alerts by default. The first alert triggers
when the budget is _forecasted_ to exceed 100%, the second triggers when the
budget _exceeds_ 100%.
-See [How to respond to billing alerts](../howtos/respond-to-billing-alerts.md)
+See [How to respond to billing alerts](site:howtos/cloud-platform/respond-to-billing-alerts.md)
for information on how to handle these alerts when they're triggered.
### Tags/labels
@@ -69,14 +69,14 @@ by the Head of DevOps, [Abraham
Martin](https://www.lookup.cam.ac.uk/person/crsid/amc203).
<figure markdown>
-
+
<figcaption>An image showing the "cost-centre" and "team" labels assigned to an
example product's meta project.</figcaption>
</figure>
## See also
-- [How to respond to billing alerts](../howtos/respond-to-billing-alerts.md)
+- [How to respond to billing alerts](site:howtos/cloud-platform/respond-to-billing-alerts.md)
[^1]:
Our reseller, TI Sparkle (or just Sparkle), is an Italian company which is
diff --git a/docs/explanations/cloud-platform/gcp-cloud-run-app-module.md b/docs/explanations/cloud-platform/gcp-cloud-run-app-module.md
index 20c9c768b60da1d69ef0bfcf27736bb18451b8f1..c406f4f9045cc1e11cdce73140b5e78e095d307d 100644
--- a/docs/explanations/cloud-platform/gcp-cloud-run-app-module.md
+++ b/docs/explanations/cloud-platform/gcp-cloud-run-app-module.md
@@ -8,7 +8,7 @@ This document outlines the changes and considerations required when migrating fr
versions of the [Google Cloud Run application terraform module](
https://gitlab.developers.cam.ac.uk/uis/devops/infra/terraform/gcp-cloud-run-app/) to version
`9.0.0` and above. For step-by-step migration instructions please see the associated [How-to page](
-../howtos/migrate-a-gcp-cloud-run-app-terraform-deployment-to-v9.md).
+site:howtos/development/migrate-a-gcp-cloud-run-app-terraform-deployment-to-v9.md).
Before the release of version [9.0.0](
https://gitlab.developers.cam.ac.uk/uis/devops/infra/terraform/gcp-cloud-run-app/-/releases/9.0.0),
diff --git a/docs/explanations/cloud-platform/gke-gitlab-runners.md b/docs/explanations/cloud-platform/gke-gitlab-runners.md
index 9f06a570bf02e8a72c9aee7bf679baa236af6278..33f4cc130150a816260e854c1c1076a098fd7452 100644
--- a/docs/explanations/cloud-platform/gke-gitlab-runners.md
+++ b/docs/explanations/cloud-platform/gke-gitlab-runners.md
@@ -93,8 +93,8 @@ takes some time to prepare the certificates. This is to avoid the
## See also
- [How to register GKE-hosted GitLab
- runners](../howtos/gke-gitlab-runners/register-a-gke-gitlab-runner.md)
+ runners](site:howtos/gke-gitlab-runners/register-a-gke-gitlab-runner.md)
- [How to run CI/CD jobs on a GKE-hosted GitLab
- runner](../howtos/gke-gitlab-runners/run-ci-jobs-on-a-gke-gitlab-runner.md)
+ runner](site:howtos/gke-gitlab-runners/run-ci-jobs-on-a-gke-gitlab-runner.md)
- [How to access a Google Secret Manager secret using service account
- impersonation](../howtos/gke-gitlab-runners/access-secrets-in-ci-jobs-using-impersonation.md)
+ impersonation](site:howtos/gke-gitlab-runners/access-secrets-in-ci-jobs-using-impersonation.md)
diff --git a/docs/explanations/cloud-platform/google-cloud-permissions-model.md b/docs/explanations/cloud-platform/google-cloud-permissions-model.md
index 348da9f351628ffc674a9f74e2279d48e96e772a..d1b7dfb6af435d7d3a017d05ae0173d8761fb54a 100644
--- a/docs/explanations/cloud-platform/google-cloud-permissions-model.md
+++ b/docs/explanations/cloud-platform/google-cloud-permissions-model.md
@@ -103,5 +103,5 @@ additionally be able to modify Cloud Scheduler, Cloud Filestore and Pub/Sub reso
## See also
-- [How to start a new product](../howtos/bootstrap-a-product.md)
+- [How to start a new product](site:howtos/products/bootstrap-a-product.md)
- [The explainer guide on our service infrastructure](./service-infrastructure.md)
diff --git a/docs/explanations/cloud-platform/service-infrastructure.md b/docs/explanations/cloud-platform/service-infrastructure.md
index 09713beb6a04bea8bcd232110a312f3f7a823815..125ea23589959537407b161c5076eb3f60a2e7ac 100644
--- a/docs/explanations/cloud-platform/service-infrastructure.md
+++ b/docs/explanations/cloud-platform/service-infrastructure.md
@@ -11,8 +11,8 @@ This document covers a few different *technical* meanings of "product" in DevOps
decide how to group service infrastructure resources into products.
There are quicker task-focused guides if all you want to do is [start a new
-service](../howtos/bootstrap-a-product.md) or [ensure an existing service is
-up-to-date](../howtos/check-product-configuration.md).
+service](site:howtos/products/bootstrap-a-product.md) or [ensure an existing service is
+up-to-date](site:howtos/products/check-product-configuration.md).
This document is long, dense and necessarily pedantic with terminology. We'd recommend getting your
drink of choice and reading the document a few times from top-to-bottom.
@@ -40,7 +40,7 @@ multiple Google Cloud "products" sharing a single GitLab "product".
The *common case*, and the preferable one, is to align Google's, GitLab's and GitLab CI's idea of a
"product" with one another and to have exactly one "product" for a given service. That situation is
-covered in a [dedicated how-to guide](../howtos/bootstrap-a-product.md).
+covered in a [dedicated how-to guide](site:howtos/products/bootstrap-a-product.md).
As services split and merge, however, we may find that the case becomes more complex. This document
explains what we mean by "product" in each of these cases, what the relationship between products
@@ -208,7 +208,7 @@ often have IAM permissions on multiple products.
!!! tip
More detail on excatly *what* Google Cloud resources are created for a product can be found in a
- [dedicated reference guide](../reference/cloud-platform/index.md). This section focuses on
+ [dedicated reference guide](site:reference/cloud-platform). This section focuses on
resources which interact with other bits of service infrastructure.
The configuration in `gcp-product-factory` is responsible for creating:
@@ -523,10 +523,10 @@ require you knowing the `gcp-product-factory` or `gitlab-runner-infrastructure`
<code>principalSet://iam.googleapis.com/projects/421963284348/locations/global/workloadIdentityPools/gitlab/attribute.gitlab_namespace_id/<em>«numeric-gitlab-namespace-id»</em></code>
* CI jobs running triggered by a specific GitLab user:
<code>principalSet://iam.googleapis.com/projects/421963284348/locations/global/workloadIdentityPools/gitlab/attribute.gitlab_user_id/<em>«numeric-gitlab-user-id»</em></code>
-* GitLab CI/CD Runner principals ([documentation](../explanations/gke-gitlab-runners.md)):
+* GitLab CI/CD Runner principals ([documentation](site:explanations/cloud-platform/gke-gitlab-runners.md)):
* Any CI job running within a specific GitLab CI runner:
<code>serviceAccount:gitlab-runner-prod-22257483.svc.id.goog[<em>«runner-product-name»</em>/gke-ci-run]</code>
-* Product-wide Google Project principals ([documentation](../reference/cloud-platform/permissions-and-roles.md)):
+* Product-wide Google Project principals ([documentation](site:reference/cloud-platform/permissions-and-roles.md)):
* Generic CI service account for CI not based in GitLab or if CI/CD jobs prefer to impersonate:
<code>serviceAccount:gke-ci-run@<em>«meta-project-id»</em>.iam.gserviceaccount.com</code>
* GitLab API token secret accessor:
@@ -714,6 +714,6 @@ flowchart TB
After reading this guide, the following pages may be of interest:
-* [How-to configure the common-case](../howtos/bootstrap-a-product.md)
-* [More information on our Google Cloud deployments](../reference/cloud-platform/index.md)
-* [How we run GitLab CI/CD runners in the Cloud](../explanations/gke-gitlab-runners.md)
+* [How-to configure the common-case](site:howtos/products/bootstrap-a-product.md)
+* [More information on our Google Cloud deployments](site:reference/cloud-platform)
+* [How we run GitLab CI/CD runners in the Cloud](site:explanations/cloud-platform/gke-gitlab-runners.md)
diff --git a/docs/explanations/development/webapp-boilerplate.md b/docs/explanations/development/webapp-boilerplate.md
index cffac2377c0fa57833e06b1d98b406b0c8791955..fbac87cdd667f5f69d744f392a7d8c0426fa98d3 100644
--- a/docs/explanations/development/webapp-boilerplate.md
+++ b/docs/explanations/development/webapp-boilerplate.md
@@ -8,7 +8,7 @@ title: Webapp developer environment
??? warning "This document is appropriate for applications which do **not** have a `compose.sh` file in the root of the repository."
The presence of `compose.sh` indicates that an application is using our older development
- environment. See the [original guide](../notes/webapp-dev-environment.md) if that file is
+ environment. See the [original guide](site:notes/webapp-dev-environment.md) if that file is
present.
This document provides a more "behind the scenes" guide to how our webapp developer environment
@@ -19,14 +19,14 @@ more about the "how" and the "why" of our developer environment.
By contrast, the following documentation may be more useful if you have a specific goal or want to
learn how to get started:
-* The [reference guide](../reference/webapp-developer-environment.md) contains cut-and-paste command
+* The [reference guide](site:reference/misc/webapp-developer-environment.md) contains cut-and-paste command
snippets to quickly accomplish common tasks.
-* Our [how-to section](../howtos/index.md) contains more task-focussed guides covering how to
+* Our [how-to section](site:howtos) contains more task-focussed guides covering how to
perform specific tasks within the environment. In particular you may want to read the following
guides:
- * [Preparing your system with required software](../howtos/prepare-your-system.md).
- * [Configuring your IDE](../howtos/configure-your-ide.md).
- * [Running an application](../howtos/run-an-existing-app.md).
+ * [Preparing your system with required software](site:howtos/development/prepare-your-system.md).
+ * [Configuring your IDE](site:howtos/development/configure-your-ide.md).
+ * [Running an application](site:howtos/development/run-an-existing-app.md).
## Guiding philosophy
@@ -119,7 +119,7 @@ that they need only recall the short `poe up` command and do not need to recall
compose` command.
A list of the standard poe tasks shipped with our standard webapp developer environment can be found
-in the [reference guide](../reference/webapp-developer-environment.md).
+in the [reference guide](site:reference/misc/webapp-developer-environment.md).
Providing common tasks behind a short alias aligns with our guiding philosophy in that we're
providing both opinionated defaults about how to run and manage the application along with a
@@ -127,7 +127,7 @@ documented "paved path" for various tasks.
### Pre-commit
-We ship a number of [pre-commit checks](../howtos/setup-pre-commit-hooks.md) in the standard
+We ship a number of [pre-commit checks](site:howtos/development/setup-pre-commit-hooks.md) in the standard
environment which run various linting and auto-formatting tools over the source. These same checks
are run in CI jobs.
@@ -222,7 +222,7 @@ For most applications, this packaging is fairly light. For the production contai
The "development container" image is similar but additionally has the development time dependencies
installed into it. See the [developer environment reference
-guide](../reference/webapp-developer-environment.md#dependencies) for more information on the
+guide](site:reference/misc/webapp-developer-environment.md#dependencies) for more information on the
difference between "development time" and "run time" dependencies.
### CI/CD
diff --git a/docs/explanations/git-gitlab/git.md b/docs/explanations/git-gitlab/git.md
index 0548c2f8f2e515260f79b9f9e7c7cb01aded7100..a0d2b5453dc400bd3edf54f290b61722fa284d87 100644
--- a/docs/explanations/git-gitlab/git.md
+++ b/docs/explanations/git-gitlab/git.md
@@ -5,7 +5,7 @@ details](https://git-scm.com/book/en/v2/Git-Internals-Plumbing-and-Porcelain) in
is also a [terminology section](#terminology) at the end of this document if any of the terms used
herein are unknown.
-See the list of [external Git documentation](../reference/git-docs.md) for more in-depth
+See the list of [external Git documentation](site:reference/git-gitlab/git-docs.md) for more in-depth
information.
## Pushing and pulling
diff --git a/docs/explanations/git-gitlab/gitlab-release-automation.md b/docs/explanations/git-gitlab/gitlab-release-automation.md
index 22f66c1b60173b3f1793bfd7b2d550f60b4ef51b..83890494f90b4faf8dfa5e41e46bb0798c682af0 100644
--- a/docs/explanations/git-gitlab/gitlab-release-automation.md
+++ b/docs/explanations/git-gitlab/gitlab-release-automation.md
@@ -21,18 +21,18 @@ The `release-it` tool is very configurable and can handle many different
requirements (see [the configuration
doc](https://github.com/release-it/release-it/blob/main/docs/configuration.md)),
however, there's an example `.release-it.json` file in the [How to enable
-automated GitLab releases](../howtos/enable-automated-gitlab-releases.md) page
+automated GitLab releases](site:howtos/git-gitlab/enable-automated-gitlab-releases.md) page
which serves as a good starting point for most of our projects.
### Commit messages
-As recommended in the [Git commits](../explanations/git.md#commits) section,
+As recommended in the [Git commits](site:explanations/git-gitlab/git.md#commits) section,
teams should ideally follow the [Conventional
Commits](https://www.conventionalcommits.org/) standard for projects using the
`release-it.yml` pipeline template. This is also a requirement for the
`conventional-changelog` plugin which is configured in the example
`.release-it.json` config file in [How to enable automated GitLab
-releases](../howtos/enable-automated-gitlab-releases.md). The `release-it` tool
+releases](site:howtos/git-gitlab/enable-automated-gitlab-releases.md). The `release-it` tool
can be configured to work without Conventional Commits if required, however, it
should be noted that the `release-it.yml` pipeline template has only ever been
tested using Conventional Commits.
@@ -73,12 +73,12 @@ hotfix branches. This allows you to checkout hotfix branches from previous tags
and commit your bug fixes. You then follow the standard workflows above to
automatically release the hotfix version. See the [Creating a hotfix for a
previously released
-version](../tutorials/automating-gitlab-releases.md#creating-a-hotfix-for-a-previously-released-version)
+version](site:tutorials/automating-gitlab-releases.md#creating-a-hotfix-for-a-previously-released-version)
section of the Automating GitLab Releases tutorial for steps on how to achieve
this.
## See also
-- [How to enable automated GitLab releases](../howtos/enable-automated-gitlab-releases.md).
-- [Automating GitLab releases](../tutorials/automating-gitlab-releases.md)
+- [How to enable automated GitLab releases](site:howtos/git-gitlab/enable-automated-gitlab-releases.md).
+- [Automating GitLab releases](site:tutorials/automating-gitlab-releases.md)
tutorial.
diff --git a/docs/explanations/misc/identifiers.md b/docs/explanations/misc/identifiers.md
index 9328b5fcccf17a2eb22a06b55b16f9bf9e65bac7..fba963af0ff173a4a97c6dc7ece0a3e05ea17d51 100644
--- a/docs/explanations/misc/identifiers.md
+++ b/docs/explanations/misc/identifiers.md
@@ -19,7 +19,7 @@ We have taken a pragmatic approach in defining a common structure for identifier
precise *formatting* of the structure as flexible to allow for integration with a wider range of
systems. We discuss this in more detail below.
-There is a [separate page of well-known identifier scopes](../reference/identifiers.md) used within
+There is a [separate page of well-known identifier scopes](site:reference/misc/identifiers.md) used within
UIS. This page explains how we use identifiers in DevOps.
## Scoped and unscoped identifiers
diff --git a/docs/explanations/renovatebot/index.md b/docs/explanations/renovatebot/index.md
index c58abf099afdbd5c54006b8facd46dc4670b3cec..c91c3aa22df9a19744bf5459219259f7122bac76 100644
--- a/docs/explanations/renovatebot/index.md
+++ b/docs/explanations/renovatebot/index.md
@@ -35,7 +35,7 @@ of its abilities. Some other features which are of use to DevOps:
* Automatically applying updates from our webapp and GCP deployment boilerplate template
repositories. ([Example
MR](https://gitlab.developers.cam.ac.uk/uis/devops/experiments/rjw57/misc/-/merge_requests/4))
-* Keeping [pre-commit hooks](./webapp-boilerplate.md#pre-commit) fresh. ([Example
+* Keeping [pre-commit hooks](site:explanations/development/webapp-boilerplate.md#pre-commit) fresh. ([Example
MR](https://gitlab.developers.cam.ac.uk/uis/devops/infra/gitlab-bots-deployment/-/merge_requests/24))
* Making sure that we're always using the most recent version of our [CI
templates](https://gitlab.developers.cam.ac.uk/uis/devops/continuous-delivery/ci-templates).
@@ -157,7 +157,7 @@ This section covers some general tips-and-tricks for renovatebot.
Renovatebot can auto-assign reviewers to the MRs it creates if you make use of a `CODEOWNERS` file.
There are some limitations in renovatebot's support for this. See the [how to
-guide](../howtos/auto-assign-renovatebot-mr-reviewers.md) for more information.
+guide](site:howtos/renovatebot/auto-assign-renovatebot-mr-reviewers.md) for more information.
### Follow the dashboard issue
@@ -191,12 +191,12 @@ manager looks for, add the following to `renovate.json`:
Renovatebot can freshen hooks from [pre-commit configurations](https://pre-commit.com/) but this
support is currently in beta and you must explicitly
-[opt-in](../howtos/use-pre-commit-hooks-with-renovatebot.md).
+[opt-in](site:howtos/renovatebot/use-pre-commit-hooks-with-renovatebot.md).
### Copier
Renovatebot can try to update webapp and boilerplate configurations which make use of our [copier
-templates](../howtos/copier-create.md). In order to do this the `_src_path` *must* be of the form
+templates](site:howtos/development/copier/create.md). In order to do this the `_src_path` *must* be of the form
`https://gitlab.developers.cam.ac.uk/...`.
This can make it difficult when using private templates, such as the GCP deployment boilerplate, and
@@ -212,10 +212,10 @@ git config set --global \
The following how-to guides cover specifics of configuring renovatebot:
-* [Configure renovatebot for your projects](../howtos/start-using-renovatebot.md).
-* [Automatically assigning reviewers to MRs](../howtos/auto-assign-renovatebot-mr-reviewers.md).
+* [Configure renovatebot for your projects](site:howtos/renovatebot/start-using-renovatebot.md).
+* [Automatically assigning reviewers to MRs](site:howtos/renovatebot/auto-assign-renovatebot-mr-reviewers.md).
* [Testing per-project changes to renovatebot's
- configuration](../howtos/run-renovatebot-locally.md).
-* [Temporarily disabling renovatebot](../howtos/disable-renovatebot.md).
+ configuration](site:howtos/renovatebot/run-renovatebot-locally.md).
+* [Temporarily disabling renovatebot](site:howtos/renovatebot/disable-renovatebot.md).
* [Keep docker images fresh in terraform
- deployments](../howtos/keep-docker-image-references-fresh.md).
+ deployments](site:howtos/renovatebot/keep-docker-image-references-fresh.md).
diff --git a/docs/howtos/aws/access-aws-console.md b/docs/howtos/aws/access-aws-console.md
index 8d3a44ff2ba97db33b40f19b44ed66df4d8d8e76..a421816db543909cb91ab61d05fa409cee48295e 100644
--- a/docs/howtos/aws/access-aws-console.md
+++ b/docs/howtos/aws/access-aws-console.md
@@ -8,7 +8,7 @@ guide](./get-started-with-aws.md) then they will have a file named `.aws-helper.
the repository. This guide covers how to access the AWS console for such products.
If you're interested in the rationale and background for how we integrate with AWS, there is a
-dedicated [explainer guide](../explanations/aws.md).
+dedicated [explainer guide](site:explanations/cloud-platform/aws.md).
## Requirements and deliverables
@@ -18,7 +18,7 @@ Before you start you will need:
[template](https://gitlab.developers.cam.ac.uk/uis/devops/gcp-deploy-boilerplate),
- AWS configuration for that deployment as per the [relevant guide](./get-started-with-aws.md), and
- the ability to access the Google Cloud console for your project with "editor" rights through a
- [gcloudadmin account](./create-gcloudadmin-account.md).
+ [gcloudadmin account](site:howtos/cloud-platform/create-gcloudadmin-account.md).
At the end of the process you will have the ability to access the AWS console for each environment.
@@ -29,7 +29,7 @@ configures a related [aws-helper](https://gitlab.developers.cam.ac.uk/uis/devops
tool.
Install `pipx` as described [in the
-guidebook](https://guidebook.devops.uis.cam.ac.uk/howtos/prepare-your-system/).
+guidebook](https://guidebook.devops.uis.cam.ac.site:howtos/development/prepare-your-system/).
Install the most recent version of the `aws-helper` tool:
diff --git a/docs/howtos/aws/audit-aws-console-access.md b/docs/howtos/aws/audit-aws-console-access.md
index b6f6f89e2ce085961a6b96aa415a6ef474f49c68..833a3a49501bf41b0329a6c9b50986f4ea807e85 100644
--- a/docs/howtos/aws/audit-aws-console-access.md
+++ b/docs/howtos/aws/audit-aws-console-access.md
@@ -6,7 +6,7 @@ title: Audit AWS console access
In Google Cloud, changes made via the console or `gcloud` CLI tool are logged against the user's
`...@gcloudadmin.g.apps.cam.ac.uk` account in the [audit
log](https://cloud.google.com/logging/docs/audit). Although AWS also has an audit log, we [use a
-shared Admin role](../explanations/aws.md) to access the console and so it is not quite as
+shared Admin role](site:explanations/cloud-platform/aws.md) to access the console and so it is not quite as
straightforward to identify which individuals performed an action should that knowledge be needed
after the event.
diff --git a/docs/howtos/aws/create-aws-accounts.md b/docs/howtos/aws/create-aws-accounts.md
index bb8470f0a34ed42ce601bda7826837f4723aa220..d34f84506fcdcdf8eca05ea7ed16297ef5e936c0 100644
--- a/docs/howtos/aws/create-aws-accounts.md
+++ b/docs/howtos/aws/create-aws-accounts.md
@@ -8,7 +8,7 @@ the AWS organisational management account you will need to ask {{ gitlab_label("
complete these steps for you.
If you're interested in the rationale and background for how we integrate with AWS, there is a
-dedicated [explainer guide](../explanations/aws.md).
+dedicated [explainer guide](site:explanations/cloud-platform/aws.md).
## Requirements and deliverables
diff --git a/docs/howtos/aws/get-started-with-aws.md b/docs/howtos/aws/get-started-with-aws.md
index dfb0808dbff7eddcefedf242e527c5f26f921d29..1e3c61cf3af0cd564d8739f36126c2736dea2667 100644
--- a/docs/howtos/aws/get-started-with-aws.md
+++ b/docs/howtos/aws/get-started-with-aws.md
@@ -13,7 +13,7 @@ Cloud and so your product will also need to have a set of Google Cloud projects
you only intend to use AWS**.
If you're interested in the rationale and background for how we integrate with AWS, there is a
-dedicated [explainer guide](../explanations/aws.md).
+dedicated [explainer guide](site:explanations/cloud-platform/aws.md).
## Differences between AWS and Google Cloud
@@ -170,7 +170,7 @@ For each **AWS Account**:
**YOU WILL NEED TO UPDATE THIS POLICY OVER TIME AND THIS DEFAULT POLICY MAY BE OVERLY BROAD.**
See the [explainer guide section on the TerraformDeploy
- role](../explanations/aws.md#the-terraformdeploy-iam-role) for more information. It is
+ role](site:explanations/cloud-platform/aws.md#the-terraformdeploy-iam-role) for more information. It is
**strongly** recommended that you include an up-to-date copy of the `ServiceDeployer` policy in
your infrastructure project.
diff --git a/docs/howtos/aws/use-aws-cli.md b/docs/howtos/aws/use-aws-cli.md
index 07b663c298c7ad1d4bf048aa621abc8b60e3c13d..1e692c104f69e6c6cf9ca15a430f7a0d5bf8e3cf 100644
--- a/docs/howtos/aws/use-aws-cli.md
+++ b/docs/howtos/aws/use-aws-cli.md
@@ -9,7 +9,7 @@ the repository. This guide covers how to configure the [AWS command line
tool](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html) for such products.
If you're interested in the rationale and background for how we integrate with AWS, there is a
-dedicated [explainer guide](../explanations/aws.md).
+dedicated [explainer guide](site:explanations/cloud-platform/aws.md).
Just as only users with "editor" rights can directly manage resources in Google via the `gcloud`
command line tool, only users with "editor" rights can directly manage resources in AWS via the
@@ -23,7 +23,7 @@ Before you start you will need:
[template](https://gitlab.developers.cam.ac.uk/uis/devops/gcp-deploy-boilerplate),
- AWS configuration for that deployment as per the [relevant guide](./get-started-with-aws.md), and
- the ability to access the Google Cloud console for your project with "editor" rights through a
- [gcloudadmin account](./create-gcloudadmin-account.md).
+ [gcloudadmin account](site:howtos/cloud-platform/create-gcloudadmin-account.md).
At the end of the process you will have the ability to access the AWS console for each environment.
@@ -39,7 +39,7 @@ configures a related [aws-helper](https://gitlab.developers.cam.ac.uk/uis/devops
tool.
Install `pipx` as described [in the
-guidebook](https://guidebook.devops.uis.cam.ac.uk/howtos/prepare-your-system/).
+guidebook](https://guidebook.devops.uis.cam.ac.site:howtos/development/prepare-your-system/).
Install the most recent version of the `aws-helper` tool:
diff --git a/docs/howtos/cloud-platform/create-gcloudadmin-account.md b/docs/howtos/cloud-platform/create-gcloudadmin-account.md
index 43b0b02f4899b26ca1bd043573d8ff8aa3e660ab..1dab735678ccbb55ef718cc1e744c447ad1fbab6 100644
--- a/docs/howtos/cloud-platform/create-gcloudadmin-account.md
+++ b/docs/howtos/cloud-platform/create-gcloudadmin-account.md
@@ -12,7 +12,7 @@ Instead we prefer team members to have a dedicated "gcloudadmin" account used fo
resources in the Google Cloud console and for deploying services.
An explanation of the use of these accounts and expectations on developer's who have them is covered
-in a [dedicated explainer guide](../explanations/gcloudadmin-accounts.md).
+in a [dedicated explainer guide](site:explanations/cloud-platform/gcloudadmin-accounts.md).
This page describes the process to create a "gcloudadmin" account.
@@ -63,4 +63,4 @@ access to Google Cloud resources.
## Next steps
-* Read more about how we [configure Google Cloud](../reference/cloud-platform/index.md).
+* Read more about how we [configure Google Cloud](site:reference/cloud-platform).
diff --git a/docs/howtos/cloud-platform/respond-to-billing-alerts.md b/docs/howtos/cloud-platform/respond-to-billing-alerts.md
index 0d33af13399212213a41ccc824139ad236fd0ccb..83521f160b960643860920711124c3fdb0cce881 100644
--- a/docs/howtos/cloud-platform/respond-to-billing-alerts.md
+++ b/docs/howtos/cloud-platform/respond-to-billing-alerts.md
@@ -16,7 +16,7 @@ a corresponding GitLab issue against the
[gcp-product-factory](https://gitlab.developers.cam.ac.uk/uis/devops/infra/gcp-product-factory)
including the details from the email alert. This issue can then be worked on
using our [standard issue lifecycle
-workflow](../workflow/gitlab.md#the-issue-lifecycle).
+workflow](site:reference/workflow/gitlab.md#the-issue-lifecycle).
<figure markdown>
@@ -26,7 +26,7 @@ alert email.</figcaption>
## Alert: 100% of budget expected to be reached
-As detailed in the [Budgets and Alerts](../explanations/gcp-budgets-alerts.md)
+As detailed in the [Budgets and Alerts](site:explanations/cloud-platform/gcp-budgets-alerts.md)
section, this is the first of two default billing alerts that we configure. When
this alert is received for a particular product the steps below should be
followed.
@@ -135,4 +135,4 @@ detailed above to reach a resolution ASAP.
## See also
- [Google Cloud Platform Budgets and
- Alerts](../explanations/gcp-budgets-alerts.md)
+ Alerts](site:explanations/cloud-platform/gcp-budgets-alerts.md)
diff --git a/docs/howtos/development/copier/create.md b/docs/howtos/development/copier/create.md
index 4d03271d02a363b291bf255f88abbcf511e5606e..ceb736a88759232511032976e6b8e3fe136070e5 100644
--- a/docs/howtos/development/copier/create.md
+++ b/docs/howtos/development/copier/create.md
@@ -6,7 +6,7 @@ title: Create a new project from a template using the Copier tool
!!! Info
This how-to guide assumes that the Copier tool has been installed as described in
- [the how-to guide for preparing your system](./prepare-your-system.md).
+ [the how-to guide for preparing your system](site:howtos/development/prepare-your-system.md).
There are two copier-based boilerplate projects:
@@ -63,7 +63,7 @@ creation is the following:
!!! tip "Using https URLs for templates"
The `_src_path` URL in `.copier-answers.yml` should be a `https://...` URL to work well with
- [renovatebot](./start-using-renovatebot.md). This is fine for public templates but private
+ [renovatebot](site:howtos/renovatebot/start-using-renovatebot.md). This is fine for public templates but private
templates, such as the GCP deploy boilerplate, will need the following command to be run to tell
git to use SSH to clone those repositories:
diff --git a/docs/howtos/development/copier/migrate.md b/docs/howtos/development/copier/migrate.md
index 36f8361e7e8217987a75bfff29189c92f63f1547..5f6afc4807809b845717b6bff7176c8101f25d8e 100644
--- a/docs/howtos/development/copier/migrate.md
+++ b/docs/howtos/development/copier/migrate.md
@@ -6,7 +6,7 @@ title: Migrate an existing cookiecutter project to Copier
!!! Info
This how-to guide assumes that the Copier tool has been installed as described in
- [the how-to guide for preparing your system](./prepare-your-system.md).
+ [the how-to guide for preparing your system](site:howtos/development/prepare-your-system.md).
!!! info
For this operation it is necessary to know answers that were used initially.
diff --git a/docs/howtos/development/copier/update.md b/docs/howtos/development/copier/update.md
index a3a669882fbbcf66d2decbaaf450858340cae1cb..0f3938ae021127129c0d61cd70f8ac4054271c2b 100644
--- a/docs/howtos/development/copier/update.md
+++ b/docs/howtos/development/copier/update.md
@@ -6,7 +6,7 @@ title: Update Projects Created from Boilerplate Templates
!!! Info
This how-to guide assumes that the Copier tool has been installed as described in
- [the how-to guide for preparing your system](./prepare-your-system.md).
+ [the how-to guide for preparing your system](site:howtos/development/prepare-your-system.md).
Over time, the boilerplate is updated and it is might becomes necessary to update the project as
well with new changes. With copier it can be done in few simple steps.
diff --git a/docs/howtos/development/create-a-new-app.md b/docs/howtos/development/create-a-new-app.md
index b996d69ec92847fd631df905a1c1f3ed1447c6a2..c3d6f3882325a69fa5031dba2b4a994262017eac 100644
--- a/docs/howtos/development/create-a-new-app.md
+++ b/docs/howtos/development/create-a-new-app.md
@@ -8,13 +8,13 @@ We have a standard template for our web applications. Our template includes supp
provided alongside the application and for "pure" API applications. This guide covers how to create
a new application from our boilerplate template, starting it and running the tests.
-Read our [explainer on the webapp boilerplate](../explanations/webapp-boilerplate.md) if you're
+Read our [explainer on the webapp boilerplate](site:explanations/development/webapp-boilerplate.md) if you're
unsure if the boilerplate is right for you.
## Prepare your system
If you have not already done so, make sure you have followed our [how-to guide for preparing your
-system](./prepare-your-system.md) and installed the software which it recommends.
+system](site:howtos/development/prepare-your-system.md) and installed the software which it recommends.
We use the [copier](https://copier.readthedocs.io/) to apply our webapp templates.
Make sure that it is installed on your system via:
@@ -35,7 +35,7 @@ application.
!!! Info
More information on working with copier templates is available
- on a [dedicated page](../deployment/templates.md).
+ on a [dedicated page](site:reference/deployment/templates.md).
Start the template process via:
@@ -87,5 +87,5 @@ In this guide you learned how to create a new boilerplate application using our
## Next steps
-- Read the [developer reference](../reference/webapp-developer-environment.md) for the developer
+- Read the [developer reference](site:reference/misc/webapp-developer-environment.md) for the developer
environment.
diff --git a/docs/howtos/development/generate-api-clients.md b/docs/howtos/development/generate-api-clients.md
index a5ace8b58937c9e7773b5283271db2be52d95af0..884b320547750270582c9fbcd2a97a48398638da 100644
--- a/docs/howtos/development/generate-api-clients.md
+++ b/docs/howtos/development/generate-api-clients.md
@@ -12,7 +12,7 @@ engage in "specification-first" development where one starts with a *description
OpenAPI file and, from that specification, one generates the backend API implementation.
This how-to guide describes how to generate API clients automatically using features in the
-[common pipeline](./add-common-pipeline-to-python.md).
+[common pipeline](site:howtos/python/add-common-pipeline-to-python.md).
## Prerequisites
@@ -128,5 +128,5 @@ implementation.
## Next steps
-Read the full [reference guide](../reference/openapi-client-generation.md) for further
+Read the full [reference guide](site:reference/misc/openapi-client-generation.md) for further
customisation.
diff --git a/docs/howtos/development/get-started-developing-on-digital-admissions.md b/docs/howtos/development/get-started-developing-on-digital-admissions.md
index 7ccbb0f7a7b516b0aec79de32adf3e9d4ba6ee44..a29b73f1faa91a391ca1d1a260580b7e9970addf 100644
--- a/docs/howtos/development/get-started-developing-on-digital-admissions.md
+++ b/docs/howtos/development/get-started-developing-on-digital-admissions.md
@@ -14,7 +14,7 @@ for linters, auto-formatters, and pre-commit hooks.
## Development Environment Setup
For guidance on preparing your system, please refer to the following guide:
-[Prepare Your System guide](https://guidebook.devops.uis.cam.ac.uk/latest/howtos/prepare-your-system/).
+[Prepare Your System guide](https://guidebook.devops.uis.cam.ac.uk/latesite:howtos/development/prepare-your-system/).
This DevOps-wide resource provides detailed instructions to ensure your environment
is correctly set up for development.
@@ -38,7 +38,7 @@ In prod, use CRSid for view then swap to gcloudadmin account to make changes for
- **Instructions**:
Below is a link to a guide on how to set up a gcloudadmin account.
- [Create Gcloudadmin](https://guidebook.devops.uis.cam.ac.uk/howtos/create-gcloudadmin-account/)
+ [Create Gcloudadmin](https://guidebook.devops.uis.cam.ac.site:howtos/cloud-platform/create-gcloudadmin-account/)
- **Team Data json Link**:
[Team Data](https://gitlab.developers.cam.ac.uk/uis/devops/infra/terraform/team-data/-/blob/master/team_data.json)
diff --git a/docs/howtos/development/migrate-a-gcp-cloud-run-app-terraform-deployment-to-v9.md b/docs/howtos/development/migrate-a-gcp-cloud-run-app-terraform-deployment-to-v9.md
index 9cb210c1db66ea8c9a1487d55abcfbe1747551ab..9f1633e19ace2dca41b96c9bfcd09d3f191c8f01 100644
--- a/docs/howtos/development/migrate-a-gcp-cloud-run-app-terraform-deployment-to-v9.md
+++ b/docs/howtos/development/migrate-a-gcp-cloud-run-app-terraform-deployment-to-v9.md
@@ -18,7 +18,7 @@ _will_ require teams to perform some refactoring to migrate to. This page
describes the steps required to upgrade to version `9.0.0` from previous
versions of the module. For more information about the changes and
considerations required when migrating from previous versions to version `9.0.0`
-please see the [explanation page](../explanations/gcp-cloud-run-app-module.md).
+please see the [explanation page](site:explanations/cloud-platform/gcp-cloud-run-app-module.md).
!!! Warning
Version `9.0.0` contains breaking changes! The web application will be redeployed once new
@@ -91,7 +91,7 @@ module "webapp" {
```
If you use Copier, update your project to the latest boilerplate release following
-[the instructions](./copier-update.md).
+[the instructions](site:howtos/development/copier/copier-update.md).
At this point it is possible for Terraform to download the new module version by running
`terraform init`. The new version will be downloaded, but the command will fail as the module
syntax has changed and needs to be updated.
@@ -100,7 +100,7 @@ syntax has changed and needs to be updated.
Since the new vesion of the module has a new syntax, it is required to update the input variables
accordingly. More information about these changes can be found on the [explanation page](
-../explanations/gcp-cloud-run-app-module.md#module-variables). The full list of variables is
+site:explanations/cloud-platform/gcp-cloud-run-app-module.md#module-variables). The full list of variables is
available in the module's [README file](
https://gitlab.developers.cam.ac.uk/uis/devops/infra/terraform/gcp-cloud-run-app/-/blob/master/README.md)
@@ -145,11 +145,11 @@ In the example code mentioned above we need to update the following options:
If the project has the load balancer configured, use the `moved` blocks as shown in the
["Load balancer" block of the explanation page](
-../explanations/gcp-cloud-run-app-module.md/#load-balancer).
+site:explanations/cloud-platform/gcp-cloud-run-app-module.md/#load-balancer).
If the project has pre-deploy job configured, adjust the config in a way that is shown in the
["Other changes" block of the explanation page](
-../explanations/gcp-cloud-run-app-module.md/#other-changes).
+site:explanations/cloud-platform/gcp-cloud-run-app-module.md/#other-changes).
In our example, after all the changes, the code should look something like below:
diff --git a/docs/howtos/development/prepare-your-system.md b/docs/howtos/development/prepare-your-system.md
index df41f0b57af52674f3e7e110a31c47b36d602881..0572765932a3da027e53fde329338a0674df5931 100644
--- a/docs/howtos/development/prepare-your-system.md
+++ b/docs/howtos/development/prepare-your-system.md
@@ -21,7 +21,7 @@ installed on your system:
docker compose plugin](https://docs.docker.com/compose/install/linux/).
3. **Git.** GitHub provide a [guide on installing
git](https://github.com/git-guides/install-git). You will also need to make sure that you can
- [sign in to GitLab](./sign-in-to-gitlab.md).
+ [sign in to GitLab](site:howtos/git-gitlab/sign-in-to-gitlab.md).
4. **Python.** (Optional) On Mac machines you can use [homebrew](https://brew.sh/). On
both Linux and Mac machines you can use the system Python or use solutions such as
[pyenv](https://github.com/pyenv/pyenv) to install specific versions. We try to support
@@ -37,7 +37,7 @@ installed on your system:
on Mac machines for OpenJDK to be found**. See the homebrew page for details. On Linux, OpenJDK
will usually be available in your distribution's package manager. If your project uses
the [GitLab package registry](https://docs.gitlab.com/ee/user/packages/maven_repository/), see
- [how-to configure your Maven settings.xml](./configure-access-to-gitlab-java-repositories.md).
+ [how-to configure your Maven settings.xml](site:howtos/java/configure-access-to-gitlab-java-repositories.md).
7. **1Password cli tools.** (Optional) If you need to run scripts using the 'op' tool, follow the
[official 1Password guide](https://developer.1password.com/docs/cli/get-started/) to install
(step 1) and enable the desktop app integration (step 2).
@@ -194,4 +194,4 @@ In this guide you learned how to install software required for common developmen
## Next steps
-* Read [how to create a new web application](./create-a-new-app.md).
+* Read [how to create a new web application](site:howtos/development/create-a-new-app.md).
diff --git a/docs/howtos/development/run-an-existing-app.md b/docs/howtos/development/run-an-existing-app.md
index c19449f7724dbe315312cedf6fa2bb6f0e314ef0..c513fb8eab78fa4fbf83dff1f3110f216f2c6589 100644
--- a/docs/howtos/development/run-an-existing-app.md
+++ b/docs/howtos/development/run-an-existing-app.md
@@ -10,13 +10,13 @@ where you can access a local instance in your browser and run tests locally.
!!! warning
This guide is appropriate for applications which do **not** have a `compose.sh` file in the root
- of the repository. See the [older reference guide](../notes/webapp-dev-environment.md) if that
+ of the repository. See the [older reference guide](site:notes/webapp-dev-environment.md) if that
file is present.
## Prerequisites
If you have not already done so, make sure you have followed our [how-to guide for preparing your
-system](./prepare-your-system.md) and installed the software which it recommends. You should confirm
+system](site:howtos/development/prepare-your-system.md) and installed the software which it recommends. You should confirm
that the `docker`, `poetry` and `poe` commands are present on your `PATH` and that the `docker
compose` plugin is installed.
@@ -35,7 +35,7 @@ more information.
!!! tip
If the `README.md` file *doesn't* include something which you later find out is required for
- bootstrapping, [open an issue](./open-an-issue.md) and, if you feel comfortable, a merge request
+ bootstrapping, [open an issue](site:howtos/git-gitlab/open-an-issue.md) and, if you feel comfortable, a merge request
adding the missing information.
You may be used to manually creating a virtualenv for Python projects in a directory named `venv` or
@@ -48,7 +48,7 @@ poetry install
??? question "What is a "virtualenv" and what does "poetry install" do?"
- We cover this in the [explainer document](../explanations/webapp-boilerplate.md) about our
+ We cover this in the [explainer document](site:explanations/development/webapp-boilerplate.md) about our
webapp boilerplate.
Check that the test suite passes:
@@ -97,4 +97,4 @@ application.
## Next steps
* Read more about what you can do with our webapp developer environment in the [reference
- guide](../reference/webapp-developer-environment.md).
+ guide](site:reference/misc/webapp-developer-environment.md).
diff --git a/docs/howtos/development/run-database-migrations-when-deploying.md b/docs/howtos/development/run-database-migrations-when-deploying.md
index 1f7f5e34f02741f907b0511dac3127193317ac50..c148bed2830b5d55fb2975cc8f9e4288a0da12f4 100644
--- a/docs/howtos/development/run-database-migrations-when-deploying.md
+++ b/docs/howtos/development/run-database-migrations-when-deploying.md
@@ -81,4 +81,4 @@ database migrations.
## Next steps
-- Read more about [how we deploy via terraform](../deployment/index.md).
+- Read more about [how we deploy via terraform](site:reference/deployment).
diff --git a/docs/howtos/development/setup-pre-commit-hooks.md b/docs/howtos/development/setup-pre-commit-hooks.md
index 9404e3407d2aee901387fc6affbf36b819c6ec24..9bb0259be9f8e9a35553edfd23f3d2af9b087a2f 100644
--- a/docs/howtos/development/setup-pre-commit-hooks.md
+++ b/docs/howtos/development/setup-pre-commit-hooks.md
@@ -51,7 +51,7 @@ repos:
!!! warning
As the `rev` parameter above is hard-coded, you should also
- [set-up renovatebot](../explanations/renovatebot.md) to keep this and your project's other
+ [set-up renovatebot](site:explanations/renovatebot) to keep this and your project's other
dependencies up-to-date.
## Installing pre-commit hooks
@@ -150,5 +150,5 @@ In this how-to you learned how to set-up a standard set of pre-commit hooks on a
Further information on using pre-commit:
-- [Webapp developer environment](../explanations/webapp-boilerplate.md#pre-commit)
-- [Creating a Python package](../tutorials/creating-a-python-package.md#catching-and-fixing-style-issues)
+- [Webapp developer environment](site:explanations/development/webapp-boilerplate.md#pre-commit)
+- [Creating a Python package](site:tutorials/creating-a-python-package.md#catching-and-fixing-style-issues)
diff --git a/docs/howtos/email/register-with-user-notify.md b/docs/howtos/email/register-with-user-notify.md
index f5f14cdfa7b1c5b082b45606405d0e71a7b70fce..46ba864529860ede99f83f65fd89d1699901a3b0 100644
--- a/docs/howtos/email/register-with-user-notify.md
+++ b/docs/howtos/email/register-with-user-notify.md
@@ -2,7 +2,7 @@
title: Register your service
---
-In DevOps we have an internal [User Notify service](../libraries-tools/user-notify.md) which can be used
+In DevOps we have an internal [User Notify service](site:libraries-tools/user-notify.md) which can be used
to send email to users of your service. This guide covers how to register your service to send
email.
@@ -67,7 +67,7 @@ To use advanced features, you will need:
reports.)
- **Technical IAM principals** which are principals such as Lookup groups or Google groups which
will be able to read technical configuration information. These should ideally be Google groups
- containing [gcloudadmin accounts](./create-gcloudadmin-account.md) and are intended for complex
+ containing [gcloudadmin accounts](site:howtos/cloud-platform/create-gcloudadmin-account.md) and are intended for complex
use cases where the automated configuration provision does not suffice.
## Requesting registration
@@ -83,7 +83,7 @@ Once you have the required information you can request that your service be regi
*Very* broadly speaking, only your production and, perhaps, staging environments should be able
to send "real" email and for other environments you should instead log the emails which _would_
be sent. We have a [mailtrap
- account](../best-practice/ourtools.md#mailtrap) which can be used for an "inbox-like" view of
+ account](site:reference/best-practice/ourtools.md#mailtrap) which can be used for an "inbox-like" view of
email messages which would be sent. The opinionated Python client library also includes a
`MockSession` class if you don't need mailtrap's features and Django includes an in-memory email
backend.
diff --git a/docs/howtos/entra-azure/add-sso-sign-in.md b/docs/howtos/entra-azure/add-sso-sign-in.md
index f92248bde58ec219b8d6c3816b4f8e24d454af33..ba5ad9f0a8f7ffd0394b3672986d566e1ec1c7b1 100644
--- a/docs/howtos/entra-azure/add-sso-sign-in.md
+++ b/docs/howtos/entra-azure/add-sso-sign-in.md
@@ -17,7 +17,7 @@ on integrating SSO with web applications. Configuration varies between web frame
you will need the following information to configure sign in:
* One or more URLs providing OAuth 2.0 or OpenID Connect (OIDC) endpoints. [Appropriate values for
- University of Cambridge sign-in](../reference/entra-id.md) are provided elsewhere in the
+ University of Cambridge sign-in](site:reference/misc/entra-id.md) are provided elsewhere in the
guidebook.
* A "redirect URL" which is a URL pointing to your web application. Entra ID redirects the user
to this URL after sign in is completed. **This URL is web framework dependant.**
@@ -266,7 +266,7 @@ configuration.
We have a [team data
file](https://gitlab.developers.cam.ac.uk/uis/devops/infra/terraform/team-data/-/blob/master/team_data.json)
which drives memberships of groups automatically. This file is documented on [a separate
-page](../explanations/service-infrastructure.md#delivery-team-user-accounts-and-groups) of the
+page](site:explanations/cloud-platform/service-infrastructure.md#delivery-team-user-accounts-and-groups) of the
guidebook. If you are using manual fetching of secrets, it is best if you grant access to a group of
users. Try to limit the set of users to only those people who need to access the secret in order to
deploy the application.
@@ -305,7 +305,7 @@ credential_secrets:
### Granting an individual user access
If you don't have a useful group defined in the team data file, you can grant access to individuals.
-We prefer using [gcloudadmin accounts](./create-gcloudadmin-account.md) when possible.
+We prefer using [gcloudadmin accounts](site:howtos/cloud-platform/create-gcloudadmin-account.md) when possible.
To grant a user access to the secret:
@@ -353,4 +353,4 @@ how to store them in a Google Cloud secret using a custom format for your applic
## Next steps
* [Use custom roles to add authorisation to your apps](./authorise-web-apps-with-custom-roles.md).
-* [Learn more about Azure and Entra ID Applications](../explanations/azure-and-entra-id-apps.md).
+* [Learn more about Azure and Entra ID Applications](site:explanations/cloud-platform/azure-and-entra-id-apps.md).
diff --git a/docs/howtos/entra-azure/authorise-web-apps-with-custom-roles.md b/docs/howtos/entra-azure/authorise-web-apps-with-custom-roles.md
index 53a106cab01291a271e999bbb400cc75f9b92d85..95d8c1cb44bfd93a833593329c56cba5699c3f1f 100644
--- a/docs/howtos/entra-azure/authorise-web-apps-with-custom-roles.md
+++ b/docs/howtos/entra-azure/authorise-web-apps-with-custom-roles.md
@@ -106,4 +106,4 @@ applications.
## Next steps
-* [Read more about Azure and Entra ID applications](../explanations/azure-and-entra-id-apps.md).
+* [Read more about Azure and Entra ID applications](site:explanations/cloud-platform/azure-and-entra-id-apps.md).
diff --git a/docs/howtos/entra-azure/register-azure-api-management-app.md b/docs/howtos/entra-azure/register-azure-api-management-app.md
index e57cbdc6327e48fd354f3b7757e6bf4134587a79..5356e00634905a04d8fc013eadd42c9b6c450832 100644
--- a/docs/howtos/entra-azure/register-azure-api-management-app.md
+++ b/docs/howtos/entra-azure/register-azure-api-management-app.md
@@ -150,4 +150,4 @@ management and how to test that you can obtain an access token.
## Next steps
-* [Learn more about Azure and Entra ID Applications](../explanations/azure-and-entra-id-apps.md).
+* [Learn more about Azure and Entra ID Applications](site:explanations/cloud-platform/azure-and-entra-id-apps.md).
diff --git a/docs/howtos/git-gitlab/common-git-tasks.md b/docs/howtos/git-gitlab/common-git-tasks.md
index e5597f3f661be33620237e49b882d3832dfdc030..e56375896bcfe6ad6b7eba3e250c1c488a3863ff 100644
--- a/docs/howtos/git-gitlab/common-git-tasks.md
+++ b/docs/howtos/git-gitlab/common-git-tasks.md
@@ -157,5 +157,5 @@ above._
## Next steps
-* Learn more about [git concepts](../explanations/git.md).
-* See a list of [recommended external git documentation](../reference/git-docs.md).
+* Learn more about [git concepts](site:explanations/git-gitlab/git.md).
+* See a list of [recommended external git documentation](site:reference/git-gitlab/git-docs.md).
diff --git a/docs/howtos/git-gitlab/create-a-feature-branch.md b/docs/howtos/git-gitlab/create-a-feature-branch.md
index ebb5b11aec8dd26dd4fa0929d6afcec95d8c27ee..879251832ffe3c0b8635fc5972a53b774d0e667c 100644
--- a/docs/howtos/git-gitlab/create-a-feature-branch.md
+++ b/docs/howtos/git-gitlab/create-a-feature-branch.md
@@ -37,5 +37,5 @@ push changes.
## Next steps
-* Learn more about [git concepts](../explanations/git.md).
-* See a list of [recommended external git documentation](../reference/git-docs.md).
+* Learn more about [git concepts](site:explanations/git-gitlab/git.md).
+* See a list of [recommended external git documentation](site:reference/git-gitlab/git-docs.md).
diff --git a/docs/howtos/git-gitlab/enable-automated-gitlab-releases.md b/docs/howtos/git-gitlab/enable-automated-gitlab-releases.md
index eb424d0192b7dcce52126c666447190d05559c66..34954f77c3ed916467885e396a54bdf7cd7194d9 100644
--- a/docs/howtos/git-gitlab/enable-automated-gitlab-releases.md
+++ b/docs/howtos/git-gitlab/enable-automated-gitlab-releases.md
@@ -8,8 +8,8 @@ This guide shows you how to enable automated releases of your GitLab code using
the [release-it](https://github.com/release-it/release-it) tool via our
[`release-it.yml`](https://gitlab.developers.cam.ac.uk/uis/devops/continuous-delivery/ci-templates/-/blob/master/auto-devops/release-it.yml)
GitLab template. For detailed information on how this process works, see the
-[GitLab Release Automation](../explanations/gitlab-release-automation.md) page
-in the [Learn](../tutorials/index.md) section.
+[GitLab Release Automation](site:explanations/git-gitlab/gitlab-release-automation.md) page
+in the [Learn](site:tutorials) section.
## Prerequisites
@@ -62,7 +62,7 @@ most of our projects.
!!! warning
The release it CI jobs are added as part of the [common
- pipeline](./add-common-pipeline-to-python.md) but can be added to projects not using the common
+ pipeline](site:howtos/python/add-common-pipeline-to-python.md) but can be added to projects not using the common
pipeline by adding an appropriate `include` statement to your CI config which references [the
template](https://gitlab.developers.cam.ac.uk/uis/devops/continuous-delivery/ci-templates/-/blob/master/auto-devops/release-it.yml?ref_type=heads):
@@ -77,7 +77,7 @@ most of our projects.
For further information on how this process works see the following.
-- [GitLab release automation](../explanations/gitlab-release-automation.md)
+- [GitLab release automation](site:explanations/git-gitlab/gitlab-release-automation.md)
explanation.
-- [Automating GitLab releases](../tutorials/automating-gitlab-releases.md)
+- [Automating GitLab releases](site:tutorials/automating-gitlab-releases.md)
tutorial.
diff --git a/docs/howtos/git-gitlab/open-an-issue.md b/docs/howtos/git-gitlab/open-an-issue.md
index 61bee7e37f9bf2a17d99072b47a819345e9e5ca2..4962e9a86c48f6681b5fcc07f9a7c9a686bf3eee 100644
--- a/docs/howtos/git-gitlab/open-an-issue.md
+++ b/docs/howtos/git-gitlab/open-an-issue.md
@@ -7,7 +7,7 @@ title: Open an issue
We use issues to track individual units of work. We use the University's GitLab
instance at <https://gitlab.developers.cam.ac.uk/> to manage them. If you've not
yet signed in to GitLab, see the [signing in to GitLab
-how-to](./sign-in-to-gitlab.md).
+how-to](site:howtos/git-gitlab/sign-in-to-gitlab.md).
This how-to covers creating issues and their structure.
@@ -15,7 +15,7 @@ This how-to covers creating issues and their structure.
The first step is finding the correct project in GitLab in which to open an
issue. These *should* be linked from the appropriate [service
-page](../services/index.md). If not, the top-level view of [DevOps GitLab
+page](site:services). If not, the top-level view of [DevOps GitLab
groups](https://gitlab.developers.cam.ac.uk/uis/devops) can be used to find an
appropriate project.
@@ -23,7 +23,7 @@ appropriate project.
Some projects are visible to DevOps members only. If you can't find a
project which you think should exist and you're not a member of DevOps
please follow the instructions on the [contact us
- page](../home/contact/index.md).
+ page](site:home/contact).
## Search for existing issues
@@ -49,7 +49,7 @@ To create a new issue:
8. Add an `issueType::...` label if the template did not do so already.
9. Consider adding special-use labels such as {{ gitlab_label("chore") }} or {{
gitlab_label("good first issue") }}. See the [labels
- reference](../reference/gitlab-labels.md) for possible labels.
+ reference](site:reference/git-gitlab/gitlab-labels.md) for possible labels.
## Summary
@@ -58,5 +58,5 @@ issue within it.
## Next steps
-* Learn about [writing good issues](../explanations/good-issues.md).
-* See how we use [GitLab labels on issues](../reference/gitlab-labels.md).
+* Learn about [writing good issues](site:explanations/git-gitlab/good-issues.md).
+* See how we use [GitLab labels on issues](site:reference/git-gitlab/gitlab-labels.md).
diff --git a/docs/howtos/git-gitlab/sign-in-to-gitlab.md b/docs/howtos/git-gitlab/sign-in-to-gitlab.md
index 80d72cb94f016878574b39424da5ca63e4a2cb39..1319e58045c79e88afa993706b6989e80c8da325 100644
--- a/docs/howtos/git-gitlab/sign-in-to-gitlab.md
+++ b/docs/howtos/git-gitlab/sign-in-to-gitlab.md
@@ -34,4 +34,4 @@ In this how-to, you learned how to sign in to GitLab using GitLab.
## Next steps
-* Try [opening an issue](./open-an-issue.md).
+* Try [opening an issue](site:howtos/git-gitlab/open-an-issue.md).
diff --git a/docs/howtos/git-gitlab/size-issues.md b/docs/howtos/git-gitlab/size-issues.md
index d97e1b63610b5b3059a36c74a1c54d7e53d8acd5..576746d4ba96f124bec1ff056cd84219a54c70ed 100644
--- a/docs/howtos/git-gitlab/size-issues.md
+++ b/docs/howtos/git-gitlab/size-issues.md
@@ -82,5 +82,5 @@ In this guide, you learned how we size issues.
## Next steps
-- Learn about [writing good issues](../explanations/good-issues.md).
-- See how we use [GitLab labels on issues](../reference/gitlab-labels.md).
+- Learn about [writing good issues](site:explanations/git-gitlab/good-issues.md).
+- See how we use [GitLab labels on issues](site:reference/git-gitlab/gitlab-labels.md).
diff --git a/docs/howtos/gke-gitlab-runners/access-secrets-in-ci-jobs-using-impersonation.md b/docs/howtos/gke-gitlab-runners/access-secrets-in-ci-jobs-using-impersonation.md
index 685bd4d1eeef1bdabec4172243e6bfd34aee79c9..136192ae025e4a6a24fd76b5e640130c7b71e42f 100644
--- a/docs/howtos/gke-gitlab-runners/access-secrets-in-ci-jobs-using-impersonation.md
+++ b/docs/howtos/gke-gitlab-runners/access-secrets-in-ci-jobs-using-impersonation.md
@@ -100,4 +100,4 @@ account to retrieve the secret value from a CI job script.
## See also
-- [GKE GitLab Runners explanation](../../explanations/gke-gitlab-runners.md)
+- [GKE GitLab Runners explanation](site:explanations/cloud-platform/gke-gitlab-runners.md)
diff --git a/docs/howtos/gke-gitlab-runners/developer-overview.md b/docs/howtos/gke-gitlab-runners/developer-overview.md
index 2df15d07beb039e1ce564141d80a984eac0abdf3..e9b209fb4fb30c17cb19d6da5333942466ff2367 100644
--- a/docs/howtos/gke-gitlab-runners/developer-overview.md
+++ b/docs/howtos/gke-gitlab-runners/developer-overview.md
@@ -33,7 +33,7 @@ will automatically run on the correct runner.
## What should I read next?
-- [GitLab CI runners](../../explanations/service-infrastructure.md#gitlab-ci-runners): Explains the
+- [GitLab CI runners](site:explanations/cloud-platform/service-infrastructure.md#gitlab-ci-runners): Explains the
architecture of the GitLab runners in UIS.
- [How to register GKE-hosted GitLab runners](./register-a-gke-gitlab-runner.md):
A guide on how to deploy/register Google Kubernetes Engine (GKE) hosted GitLab runners.
diff --git a/docs/howtos/gke-gitlab-runners/register-a-gke-gitlab-runner.md b/docs/howtos/gke-gitlab-runners/register-a-gke-gitlab-runner.md
index 54f32e4575fb791def3c6c9e8de23d109de6755c..81699b9ca3b8ff3fae9466eea324023350e73f9a 100644
--- a/docs/howtos/gke-gitlab-runners/register-a-gke-gitlab-runner.md
+++ b/docs/howtos/gke-gitlab-runners/register-a-gke-gitlab-runner.md
@@ -10,7 +10,7 @@ for products deployed by the
repository.
For more information on the GKE runner configuration, see
-[gke-gitlab-runners](../../reference/cloud-platform/gke-gitlab-runners.md) in the
+[gke-gitlab-runners](site:reference/cloud-platform/gke-gitlab-runners.md) in the
reference section.
## Prerequisites
@@ -30,7 +30,7 @@ The following information will be required to complete the steps in this guide.
1. Clone the
[`gitlab-runner-infrastructure`](https://gitlab.developers.cam.ac.uk/uis/devops/devhub/gitlab-runner-infrastructure)
repository to your local machine.
-2. Create a [new feature branch](../../explanations/git.md#feature-branches) for your changes.
+2. Create a [new feature branch](site:explanations/git-gitlab/git.md#feature-branches) for your changes.
3. In `locals.tf`, add your new product to the `product_runners.production` map using the
information from the prerequisites section above. For example, if you are adding a new product
called `test-product` you might do the following.
@@ -52,7 +52,7 @@ The following information will be required to complete the steps in this guide.
}
```
-4. [Commit](../../explanations/git.md#commits) your changes, push your branch to the remote, and
+4. [Commit](site:explanations/git-gitlab/git.md#commits) your changes, push your branch to the remote, and
open a merge request.
5. The merge request should be reviewed, merged, and deployed by a member of the Cloud Team.
Deployment steps can be found in the
diff --git a/docs/howtos/gke-gitlab-runners/run-ci-jobs-on-a-gke-gitlab-runner.md b/docs/howtos/gke-gitlab-runners/run-ci-jobs-on-a-gke-gitlab-runner.md
index 680fe4afb1504a54703662a4c83e50b55956ecd5..efaab37ecde211f8d68b8970e78d56004742d399 100644
--- a/docs/howtos/gke-gitlab-runners/run-ci-jobs-on-a-gke-gitlab-runner.md
+++ b/docs/howtos/gke-gitlab-runners/run-ci-jobs-on-a-gke-gitlab-runner.md
@@ -11,7 +11,7 @@ this see the **explanation on GKE-hosted runners**.
## Prerequisites
- Ensure that the product in question has been configured with a GKE-hosted GitLab runner. See [GKE
- GitLab Runners](../../reference/cloud-platform/gke-gitlab-runners.md) for more information.
+ GitLab Runners](site:reference/cloud-platform/gke-gitlab-runners.md) for more information.
## Steps
diff --git a/docs/howtos/java/add-common-pipeline-and-precommit-to-java.md b/docs/howtos/java/add-common-pipeline-and-precommit-to-java.md
index 64834ad05cf18040e2759593d3eea5ded53df27a..427e147da72deba41fd152ceeee0cd08ef0b41bc 100644
--- a/docs/howtos/java/add-common-pipeline-and-precommit-to-java.md
+++ b/docs/howtos/java/add-common-pipeline-and-precommit-to-java.md
@@ -139,7 +139,7 @@ retrieve secrets from Secrets Manager.
## Add the google-java-format pre-commit plugin
The google-java-format pre-commit plugin should also be
-[added to the project](../howtos/setup-pre-commit-hooks.md#java).
+[added to the project](site:howtos/development/setup-pre-commit-hooks.md#java).
## IDE formatter configuration
diff --git a/docs/howtos/products/bootstrap-a-product.md b/docs/howtos/products/bootstrap-a-product.md
index 487b832b88ae8c25d3db4d520f07c108c4efa00d..43fb9809f88c9d150e882f26d8af67dfc063bcf3 100644
--- a/docs/howtos/products/bootstrap-a-product.md
+++ b/docs/howtos/products/bootstrap-a-product.md
@@ -14,14 +14,14 @@ This guide is intentionally brief. If you have questions when reading, see the f
for additional context:
* Tutorials
- * [Bootstrapping a new web-application product](../tutorials/bootstrapping-a-new-application.md)
+ * [Bootstrapping a new web-application product](site:tutorials/bootstrapping-a-new-application.md)
* Explainers
- * [How our service infrastructure is configured](../explanations/service-infrastructure.md)
- * [GitLab CI runners](../explanations/gke-gitlab-runners.md)
+ * [How our service infrastructure is configured](site:explanations/cloud-platform/service-infrastructure.md)
+ * [GitLab CI runners](site:explanations/cloud-platform/gke-gitlab-runners.md)
* Reference
- * [How we deploy to Google Cloud](../deployment/index.md)
- * [Google Cloud projects and folders](../reference/cloud-platform/index.md)
- * [How GitLab CI runners are deployed](../reference/cloud-platform/gke-gitlab-runners.md)
+ * [How we deploy to Google Cloud](site:reference/deployment)
+ * [Google Cloud projects and folders](site:reference/cloud-platform)
+ * [How GitLab CI runners are deployed](site:reference/cloud-platform/gke-gitlab-runners.md)
## Decide on the development team
@@ -70,7 +70,7 @@ Optionally, there are other fields you can provide:
* msteams_channel_webhook_urls: allows you to specify a Microsoft Teams channel to receive
notifications from Google Cloud. This is useful for monitoring and alerting purposes.
- See [MS Teams Workflows Webhooks](msteams-workflows-webhooks.md)
+ See [MS Teams Workflows Webhooks](site:howtos/msteams/workflows-webhooks.md)
Open an issue in
[gcp-product-factory](https://gitlab.developers.cam.ac.uk/uis/devops/infra/gcp-product-factory/) and
@@ -152,7 +152,7 @@ Usually you'll want to create two projects to start with:
* a `webapp` project which holds Python code based on our [web application
boilerplate](https://gitlab.developers.cam.ac.uk/uis/devops/webapp-boilerplate/).
-We are [open by default](../workflow/gitlab.md#open-by-default) and so the visibility of `webapp`
+We are [open by default](site:reference/workflow/gitlab.md#open-by-default) and so the visibility of `webapp`
can be `public` and should not be less than `internal`. As the infrastructure project can be
externally sensitive, we recommend having the visibility of `infrastructure` be at most `internal`.
@@ -200,9 +200,9 @@ projects = {
??? "What is `container_expiration_policy`?"
- Our [common CI pipeline](../howtos/add-common-pipeline-to-python.md) will automatically build
+ Our [common CI pipeline](site:howtos/python/add-common-pipeline-to-python.md) will automatically build
container images. If you are using [release
- automation](../howtos/enable-automated-gitlab-releases.md), images corresponding to released
+ automation](site:howtos/git-gitlab/enable-automated-gitlab-releases.md), images corresponding to released
versions will be tagged with names of the form `{x}.{y}.{z}` and automatically pushed to Google
Cloud for later deployment.
@@ -263,7 +263,7 @@ locals {
```
Once {{ gitlab_label("team::Cloud") }} have addressed your issue, you can [create a new
-application](./create-a-new-app.md).
+application](site:howtos/development/create-a-new-app.md).
## Summary
@@ -273,5 +273,5 @@ product in all three places ready for development to start.
## Next steps
-* [Bootstrap a new web application](./create-a-new-app.md) from our boilerplate.
-* [Deploy the empty application to Google Cloud](../deployment/index.md).
+* [Bootstrap a new web application](site:howtos/development/create-a-new-app.md) from our boilerplate.
+* [Deploy the empty application to Google Cloud](site:reference/deployment).
diff --git a/docs/howtos/products/check-product-configuration.md b/docs/howtos/products/check-product-configuration.md
index eb1b974917966ad90f51aca46ff299aed6b04e3d..fce4fdecda01bdae16d4f8f6edebe3000b5a1f6c 100644
--- a/docs/howtos/products/check-product-configuration.md
+++ b/docs/howtos/products/check-product-configuration.md
@@ -13,7 +13,7 @@ scratch.
The word "product" can mean many things in the DevOps division. In particular what a "product" means
from a GitLab perspective may be different than from a "Google Cloud" perspective. We have a
dedicated explainer covering [products and service
-infrastructure](../explanations/service-infrastructure.md).
+infrastructure](site:explanations/cloud-platform/service-infrastructure.md).
The following sections cover the checks you should make.
diff --git a/docs/howtos/products/delete-product-infrastructure.md b/docs/howtos/products/delete-product-infrastructure.md
index 23d473711e99a4f520be0e203b7997d18b52662f..413fd88f47cc7fb8aff720a6ce3ac35a56693eac 100644
--- a/docs/howtos/products/delete-product-infrastructure.md
+++ b/docs/howtos/products/delete-product-infrastructure.md
@@ -14,7 +14,7 @@ related to the product are stored across several Git repositories with Terraform
* [Google Cloud Product Factory](https://gitlab.developers.cam.ac.uk/uis/devops/infra/gcp-product-factory)
As our cloud platform deployment [comprises multiple stages](
-../reference/cloud-platform/index.md), it must be deleted in a strict order. The following
+site:reference/cloud-platform), it must be deleted in a strict order. The following
information illustrates the right order.
!!! Info
@@ -26,7 +26,7 @@ information illustrates the right order.
First, it is needed to delete the top-level infrastructure, i.e. resources that are used
by the product's deployment (Cloud SQL instances, Cloud Run instances, so on).
-Almost all infrastructure projects were created from [the template](../deployment/templates.md).
+Almost all infrastructure projects were created from [the template](site:reference/deployment/templates.md).
However, the set of resources may vary from product to product (e.g. some products use the MySQL
database and others use the PostgreSQL database), so there is no universal solution.
The general steps are as follows:
diff --git a/docs/howtos/python/publish-a-python-package.md b/docs/howtos/python/publish-a-python-package.md
index 3c9abdff7ff99b430b18904f56d1ddc9485419da..4a594966eb9f7877774c89549f70ac6f3cd3da1c 100644
--- a/docs/howtos/python/publish-a-python-package.md
+++ b/docs/howtos/python/publish-a-python-package.md
@@ -9,10 +9,10 @@ title: Publish a package
This page assumes that you are working with an *existing* Python package
which has been configured for auto-publishing via our common pipeline.
See [how to add the common pipeline to a Python
- package](./add-common-pipeline-to-python.md) if this has not been done.
+ package](site:howtos/python/add-common-pipeline-to-python.md) if this has not been done.
If you want to learn more about how we structure Python packages, follow
- [our Python package tutorial](../tutorials/creating-a-python-package.md).
+ [our Python package tutorial](site:tutorials/creating-a-python-package.md).
Python packages which make use of our common pipeline are set up to auto-publish
packages when a new git tag is pushed.
@@ -78,4 +78,4 @@ project.
## Next steps
* See [how to add the common pipeline to an existing Python
- package](./add-common-pipeline-to-python.md).
+ package](site:howtos/python/add-common-pipeline-to-python.md).
diff --git a/docs/howtos/python/pypi.md b/docs/howtos/python/pypi.md
index 0f52213571f199808fcc6ef6e4276639e10ab011..a948b3d6b2bebcca0b5962b3cd5d45103eae060f 100644
--- a/docs/howtos/python/pypi.md
+++ b/docs/howtos/python/pypi.md
@@ -10,7 +10,7 @@ Python package to the public PyPI repository.
!!! info
This document is a goal-oriented "how-to" guide. We have a separate
- [explainer page](../workflow/pypi.md) which goes into more details on
+ [explainer page](site:reference/workflow/pypi.md) which goes into more details on
the "why" of this process.
## Sign in to PyPI
diff --git a/docs/howtos/renovatebot/deploy-releases-with-renovatebot.md b/docs/howtos/renovatebot/deploy-releases-with-renovatebot.md
index fda495a26006446e5fdf37bffc182e687ce6beaf..52a28f72f35025b886e5d4287faa7c31c0acbcbd 100644
--- a/docs/howtos/renovatebot/deploy-releases-with-renovatebot.md
+++ b/docs/howtos/renovatebot/deploy-releases-with-renovatebot.md
@@ -29,9 +29,9 @@ deployment projects when new releases of your web app are made in GitLab.
## Prerequisites
Your upstream web app projects must have [release automation
-enabled](./enable-automated-gitlab-releases.md) and use [semver](https://semver.org/) versioning.
+enabled](site:howtos/git-gitlab/enable-automated-gitlab-releases.md) and use [semver](https://semver.org/) versioning.
-You must have [enabled renovatebot](./start-using-renovatebot.md) in the deployment project holding
+You must have [enabled renovatebot](site:howtos/renovatebot/start-using-renovatebot.md) in the deployment project holding
your terraform.
## Enable the terraformWebappRelease preset
@@ -100,6 +100,6 @@ automatically open Merge Requests when new versions of the deployed web apps are
## Next steps
-* [How to configure release automation](./enable-automated-gitlab-releases.md)
+* [How to configure release automation](site:howtos/git-gitlab/enable-automated-gitlab-releases.md)
* [Manually triggering renovatebot](./trigger-renovatebot-from-gitlab-ui.md)
* [Triggering renovatebot from CI](./trigger-renovatebot-from-ci.md)
diff --git a/docs/howtos/renovatebot/trigger-renovatebot-from-ci.md b/docs/howtos/renovatebot/trigger-renovatebot-from-ci.md
index b36d378016fa681270997998c4e52e7ac95abba0..2a2cfc3cc93ddecff85b754981395dd09c5bf0dc 100644
--- a/docs/howtos/renovatebot/trigger-renovatebot-from-ci.md
+++ b/docs/howtos/renovatebot/trigger-renovatebot-from-ci.md
@@ -32,7 +32,7 @@ the project containing the CI pipeline.
## Triggering runs in other projects
Suppose you have two projects `uis/devops/puntbooking/infra` and `uis/devops/puntbooking/webapp`.
-You have [release automation](./enable-automated-gitlab-releases.md) enabled for the `webapp`.
+You have [release automation](site:howtos/git-gitlab/enable-automated-gitlab-releases.md) enabled for the `webapp`.
You have [added
configuration](https://gitlab.developers.cam.ac.uk/uis/devops/renovate-config#keeping-terraform-configurations-up-to-date-with-latest-release-of-a-web-app)
in `uis/devops/puntbooking/infra` to open Merge Requests when new releases of `webapp` are made.
diff --git a/docs/howtos/renovatebot/trigger-renovatebot-from-cli.md b/docs/howtos/renovatebot/trigger-renovatebot-from-cli.md
index 183131bbf5d8015b597d6d475e3d4c78d271ca5a..91624251bdb9f18ef479e36ffa7a94da1ff3513e 100644
--- a/docs/howtos/renovatebot/trigger-renovatebot-from-cli.md
+++ b/docs/howtos/renovatebot/trigger-renovatebot-from-cli.md
@@ -13,9 +13,9 @@ This guide covers how you can trigger a renovatebot run yourself from the comman
## Prerequisites
* The `gcloud` CLI tool must be installed as per the guide on [preparing your
- system](./prepare-your-system.md).
+ system](site:howtos/development/prepare-your-system.md).
* You must be authenticated via `gcloud auth login` with a [gcloudadmin
- account](./create-gcloudadmin-account.md).
+ account](site:howtos/cloud-platform/create-gcloudadmin-account.md).
* You must have the [httpie command line tool](https://httpie.io/) installed.
## Triggering a run
diff --git a/docs/libraries-tools/gcp-terraform.md b/docs/libraries-tools/gcp-terraform.md
index bca3948e3ffc919a71d829553b060e65b64e8b74..b6edcc43d30034ed1606401ff3500193333f920d 100644
--- a/docs/libraries-tools/gcp-terraform.md
+++ b/docs/libraries-tools/gcp-terraform.md
@@ -7,15 +7,15 @@ Our adopted & recommended tools & services for Google Cloud Platform (GCP) and T
<!-- markdownlint-disable MD013 -->
| Title | Summary | Our Docs |
|-----------------------------------------------------------------|----------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------|
-| [Cloud Run](https://cloud.google.com/run) | Serverless container platform for stateless applications | [Reference](../reference/cloud-platform/index.md), [Migration](../explanations/gcp-cloud-run-app-module.md) |
-| [Cloud SQL](https://cloud.google.com/sql) | Fully managed relational database service | [Backups](../reference/cloud-platform/backups.md) |
-| [Cloud Storage](https://cloud.google.com/storage) | Object storage service | [Reference](../reference/cloud-platform/index.md) |
-| [Cloud Load Balancing](https://cloud.google.com/load-balancing) | Scalable load distribution service | [Architecture](../standards-and-compliance/standard-architecture-diagrams.md) |
-| [Cloud DNS](https://cloud.google.com/dns) | Managed DNS service | [DNS Guide](../reference/cloud-platform/dns.md) |
-| [Secret Manager](https://cloud.google.com/secret-manager) | Secure secret storage service | [CI Access](../howtos/gke-gitlab-runners/access-secrets-in-ci-jobs-using-impersonation.md) |
-| [Cloud Monitoring](https://cloud.google.com/monitoring) | Infrastructure and application monitoring service | [Reference](../reference/cloud-platform/index.md) |
-| [Cloud Logging](https://cloud.google.com/logging) | Centralized log management service | [Reference](../reference/cloud-platform/index.md) |
-| [gcloud CLI](https://cloud.google.com/sdk/gcloud) | Command-line interface for GCP services | [System Setup](../howtos/prepare-your-system.md) |
+| [Cloud Run](https://cloud.google.com/run) | Serverless container platform for stateless applications | [Reference](site:reference/cloud-platform), [Migration](site:explanations/cloud-platform/gcp-cloud-run-app-module.md) |
+| [Cloud SQL](https://cloud.google.com/sql) | Fully managed relational database service | [Backups](site:reference/cloud-platform/backups.md) |
+| [Cloud Storage](https://cloud.google.com/storage) | Object storage service | [Reference](site:reference/cloud-platform) |
+| [Cloud Load Balancing](https://cloud.google.com/load-balancing) | Scalable load distribution service | [Architecture](site:standards-and-compliance/standard-architecture-diagrams.md) |
+| [Cloud DNS](https://cloud.google.com/dns) | Managed DNS service | [DNS Guide](site:reference/cloud-platform/dns.md) |
+| [Secret Manager](https://cloud.google.com/secret-manager) | Secure secret storage service | [CI Access](site:howtos/gke-gitlab-runners/access-secrets-in-ci-jobs-using-impersonation.md) |
+| [Cloud Monitoring](https://cloud.google.com/monitoring) | Infrastructure and application monitoring service | [Reference](site:reference/cloud-platform) |
+| [Cloud Logging](https://cloud.google.com/logging) | Centralized log management service | [Reference](site:reference/cloud-platform) |
+| [gcloud CLI](https://cloud.google.com/sdk/gcloud) | Command-line interface for GCP services | [System Setup](site:howtos/development/prepare-your-system.md) |
<!-- markdownlint-enable MD013 -->
## Terraform & Infrastructure Tools
@@ -23,9 +23,9 @@ Our adopted & recommended tools & services for Google Cloud Platform (GCP) and T
<!-- markdownlint-disable MD013 -->
| Title | Summary | Our Docs |
|------------------------------------------------------------------------------------------------|----------------------------------------------|--------------------------------------------------------------|
-| [Terraform](https://www.terraform.io/) | Infrastructure as Code tool | [Reference](../reference/cloud-platform/index.md) |
-| [terraform-provider-google](https://registry.terraform.io/providers/hashicorp/google/latest) | Google Cloud Platform provider for Terraform | [Reference](../reference/cloud-platform/index.md) |
-| [terraform-provider-aws](https://registry.terraform.io/providers/hashicorp/aws/latest) | Amazon Web Services provider for Terraform | [AWS Guide](../explanations/aws.md) |
-| [terraform-provider-azurerm](https://registry.terraform.io/providers/hashicorp/azurerm/latest) | Microsoft Azure provider for Terraform | [Azure Guide](../explanations/azure-and-entra-id-apps.md) |
-| [tflint](https://github.com/terraform-linters/tflint) | Terraform linter | [Reference](../reference/cloud-platform/index.md) |
+| [Terraform](https://www.terraform.io/) | Infrastructure as Code tool | [Reference](site:reference/cloud-platform) |
+| [terraform-provider-google](https://registry.terraform.io/providers/hashicorp/google/latest) | Google Cloud Platform provider for Terraform | [Reference](site:reference/cloud-platform) |
+| [terraform-provider-aws](https://registry.terraform.io/providers/hashicorp/aws/latest) | Amazon Web Services provider for Terraform | [AWS Guide](site:explanations/cloud-platform/aws.md) |
+| [terraform-provider-azurerm](https://registry.terraform.io/providers/hashicorp/azurerm/latest) | Microsoft Azure provider for Terraform | [Azure Guide](site:explanations/cloud-platform/azure-and-entra-id-apps.md) |
+| [tflint](https://github.com/terraform-linters/tflint) | Terraform linter | [Reference](site:reference/cloud-platform) |
<!-- markdownlint-enable MD013 -->
diff --git a/docs/libraries-tools/git-ci-docker.md b/docs/libraries-tools/git-ci-docker.md
index e11be588c42b01c9f4d0dc65558f8182f7e35440..f5366205a7613ad894987f62f61041e487d36791 100644
--- a/docs/libraries-tools/git-ci-docker.md
+++ b/docs/libraries-tools/git-ci-docker.md
@@ -5,10 +5,10 @@ Our adopted & recommended development tools & services.
<!-- markdownlint-disable MD013 -->
| Title | Summary | Our Docs |
|---------------------------------------------------------------|------------------------------------------------|----------------------------------------------------------|
-| [Docker](https://www.docker.com/) | Container platform | [System Setup](../howtos/prepare-your-system.md) |
-| [GitLab CI/CD](https://docs.gitlab.com/ee/ci/) | Continuous Integration and Deployment platform | [Tutorial](../tutorials/creating-a-python-package.md) |
+| [Docker](https://www.docker.com/) | Container platform | [System Setup](site:howtos/development/prepare-your-system.md) |
+| [GitLab CI/CD](https://docs.gitlab.com/ee/ci/) | Continuous Integration and Deployment platform | [Tutorial](site:tutorials/creating-a-python-package.md) |
| [GitLab CI Local](https://github.com/firecow/gitlab-ci-local) | Local debugging of GitLab pipelines. | |
-| [GitLab Runner](https://docs.gitlab.com/runner/) | CI/CD job execution agent | [GKE Guide](../explanations/gke-gitlab-runners.md) |
-| [renovatebot](https://www.mend.io/renovate/) | Automated dependency updates | [Guide](../explanations/renovatebot.md) |
-| [pre-commit](https://pre-commit.com/) | Git hook framework | [Setup](../howtos/setup-pre-commit-hooks.md) |
+| [GitLab Runner](https://docs.gitlab.com/runner/) | CI/CD job execution agent | [GKE Guide](site:explanations/cloud-platform/gke-gitlab-runners.md) |
+| [renovatebot](https://www.mend.io/renovate/) | Automated dependency updates | [Guide](site:explanations/renovatebot) |
+| [pre-commit](https://pre-commit.com/) | Git hook framework | [Setup](site:howtos/development/setup-pre-commit-hooks.md) |
<!-- markdownlint-enable MD013 -->
diff --git a/docs/libraries-tools/python.md b/docs/libraries-tools/python.md
index 13049d73c52c4d6b8da97e8baac10d59076cdf8d..f75dd80d810ae761e33971bcff2f1023b5cbb685 100644
--- a/docs/libraries-tools/python.md
+++ b/docs/libraries-tools/python.md
@@ -7,26 +7,26 @@ Our adopted & recommended Python libraries, snippets & tools.
<!-- markdownlint-disable MD013 -->
| Title | Summary | Our Docs |
|---------------------------------------------------------------------------------|---------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------|
-| [black](https://github.com/psf/black) | Code formatter that enforces a consistent style | [Setup](../howtos/setup-pre-commit-hooks.md), [Tutorial](../tutorials/creating-a-python-package.md) |
-| [coverage](https://coverage.readthedocs.io/) | Tool for measuring code coverage of Python programs | [Tutorial](../tutorials/creating-a-python-package.md) |
-| [docopt](http://docopt.org/) | Command-line interface description language and parser | [Tutorial](../tutorials/creating-a-python-package.md) |
-| [faker](https://faker.readthedocs.io/) | Library for generating fake data for testing | [Tutorial](../tutorials/creating-a-python-package.md) |
-| [flake8](https://flake8.pycqa.org/) | Tool for style guide enforcement and linting | [Setup](../howtos/setup-pre-commit-hooks.md), [Tutorial](../tutorials/creating-a-python-package.md) |
-| [furo](https://pradyunsg.me/furo/) | Clean customizable Sphinx documentation theme | [Tutorial](../tutorials/creating-a-python-package.md) |
-| [geddit](https://gitlab.developers.cam.ac.uk/uis/devops/lib/geddit) | UIS library for fetching data from URLs | [Tutorial](../tutorials/creating-a-python-package.md) |
-| [isort](https://pycqa.github.io/isort/) | Library for sorting Python imports | [Setup](../howtos/setup-pre-commit-hooks.md), [Tutorial](../tutorials/creating-a-python-package.md) |
-| [jsonpath-ng](https://github.com/h2non/jsonpath-ng) | Library for extracting data using JSONPath expressions | [Tutorial](../tutorials/creating-a-python-package.md) |
-| [mypy](https://mypy.readthedocs.io/) | Static type checker for Python | [Setup](../howtos/setup-pre-commit-hooks.md), [Tutorial](../tutorials/creating-a-python-package.md) |
-| [pre-commit](https://pre-commit.com/) | Framework for managing git pre-commit hooks | [Setup](../howtos/setup-pre-commit-hooks.md), [Tutorial](../tutorials/creating-a-python-package.md) |
-| [PyYAML](https://pyyaml.org/) | YAML parser and emitter for Python | [Tutorial](../tutorials/creating-a-python-package.md) |
-| [pytest](https://docs.pytest.org/) | Testing framework | [Tutorial](../tutorials/creating-a-python-package.md), [Boilerplate](../explanations/webapp-boilerplate.md#testing) |
-| [pytest-cov](https://pytest-cov.readthedocs.io/) | Coverage plugin for pytest | [Tutorial](../tutorials/creating-a-python-package.md) |
-| [pytest-mock](https://pytest-mock.readthedocs.io/) | Thin-wrapper around mock package for pytest | [Tutorial](../tutorials/creating-a-python-package.md) |
-| [python-social-auth](https://python-social-auth.readthedocs.io/) | Authentication framework for Python web frameworks | [SSO Guide](../howtos/configure-django-for-sso.md) |
-| [sphinx](https://www.sphinx-doc.org/) | Documentation generator | [Tutorial](../tutorials/creating-a-python-package.md) |
-| [sphinx-autodoc-typehints](https://github.com/tox-dev/sphinx-autodoc-typehints) | Type hints support for Sphinx | [Tutorial](../tutorials/creating-a-python-package.md) |
-| [structlog](https://www.structlog.org/) | Structured logging for Python | [Tutorial](../tutorials/creating-a-python-package.md) |
-| [tox](https://tox.wiki/) | Test automation and virtual environment management tool | [Tutorial](../tutorials/creating-a-python-package.md) |
+| [black](https://github.com/psf/black) | Code formatter that enforces a consistent style | [Setup](site:howtos/development/setup-pre-commit-hooks.md), [Tutorial](site:tutorials/creating-a-python-package.md) |
+| [coverage](https://coverage.readthedocs.io/) | Tool for measuring code coverage of Python programs | [Tutorial](site:tutorials/creating-a-python-package.md) |
+| [docopt](http://docopt.org/) | Command-line interface description language and parser | [Tutorial](site:tutorials/creating-a-python-package.md) |
+| [faker](https://faker.readthedocs.io/) | Library for generating fake data for testing | [Tutorial](site:tutorials/creating-a-python-package.md) |
+| [flake8](https://flake8.pycqa.org/) | Tool for style guide enforcement and linting | [Setup](site:howtos/development/setup-pre-commit-hooks.md), [Tutorial](site:tutorials/creating-a-python-package.md) |
+| [furo](https://pradyunsg.me/furo/) | Clean customizable Sphinx documentation theme | [Tutorial](site:tutorials/creating-a-python-package.md) |
+| [geddit](https://gitlab.developers.cam.ac.uk/uis/devops/lib/geddit) | UIS library for fetching data from URLs | [Tutorial](site:tutorials/creating-a-python-package.md) |
+| [isort](https://pycqa.github.io/isort/) | Library for sorting Python imports | [Setup](site:howtos/development/setup-pre-commit-hooks.md), [Tutorial](site:tutorials/creating-a-python-package.md) |
+| [jsonpath-ng](https://github.com/h2non/jsonpath-ng) | Library for extracting data using JSONPath expressions | [Tutorial](site:tutorials/creating-a-python-package.md) |
+| [mypy](https://mypy.readthedocs.io/) | Static type checker for Python | [Setup](site:howtos/development/setup-pre-commit-hooks.md), [Tutorial](site:tutorials/creating-a-python-package.md) |
+| [pre-commit](https://pre-commit.com/) | Framework for managing git pre-commit hooks | [Setup](site:howtos/development/setup-pre-commit-hooks.md), [Tutorial](site:tutorials/creating-a-python-package.md) |
+| [PyYAML](https://pyyaml.org/) | YAML parser and emitter for Python | [Tutorial](site:tutorials/creating-a-python-package.md) |
+| [pytest](https://docs.pytest.org/) | Testing framework | [Tutorial](site:tutorials/creating-a-python-package.md), [Boilerplate](site:explanations/development/webapp-boilerplate.md#testing) |
+| [pytest-cov](https://pytest-cov.readthedocs.io/) | Coverage plugin for pytest | [Tutorial](site:tutorials/creating-a-python-package.md) |
+| [pytest-mock](https://pytest-mock.readthedocs.io/) | Thin-wrapper around mock package for pytest | [Tutorial](site:tutorials/creating-a-python-package.md) |
+| [python-social-auth](https://python-social-auth.readthedocs.io/) | Authentication framework for Python web frameworks | [SSO Guide](site:howtos/entra-azure/configure-django-for-sso.md) |
+| [sphinx](https://www.sphinx-doc.org/) | Documentation generator | [Tutorial](site:tutorials/creating-a-python-package.md) |
+| [sphinx-autodoc-typehints](https://github.com/tox-dev/sphinx-autodoc-typehints) | Type hints support for Sphinx | [Tutorial](site:tutorials/creating-a-python-package.md) |
+| [structlog](https://www.structlog.org/) | Structured logging for Python | [Tutorial](site:tutorials/creating-a-python-package.md) |
+| [tox](https://tox.wiki/) | Test automation and virtual environment management tool | [Tutorial](site:tutorials/creating-a-python-package.md) |
<!-- markdownlint-enable MD013 -->
## Snippets
@@ -45,9 +45,9 @@ Our adopted & recommended Python libraries, snippets & tools.
<!-- markdownlint-disable MD013 -->
| Title | Summary | Our Docs |
|------------------------------------------|----------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------|
-| [copier](https://copier.readthedocs.io/) | Tool for rendering project templates | [Create](../howtos/copier-create.md), [Update](../howtos/copier-update.md), [Migrate](../howtos/copier-migrate.md) |
-| [pip](https://pip.pypa.io/) | Package installer for Python | [System Setup](../howtos/prepare-your-system.md) |
-| [pipx](https://pypa.github.io/pipx/) | Tool to install and run Python applications in isolated environments | [System Setup](../howtos/prepare-your-system.md) |
-| [poetry](https://python-poetry.org/) | Python dependency management and packaging tool | [Tutorial](../tutorials/creating-a-python-package.md), [Boilerplate](../explanations/webapp-boilerplate.md#poetry) |
-| [poe](https://poethepoet.natn.io/) | Task runner that works well with poetry | [Tutorial](../tutorials/creating-a-python-package.md), [Boilerplate](../explanations/webapp-boilerplate.md#poe) |
+| [copier](https://copier.readthedocs.io/) | Tool for rendering project templates | [Create](site:howtos/development/copier/create.md), [Update](site:howtos/development/copier/update.md), [Migrate](site:howtos/development/copier/migrate.md) |
+| [pip](https://pip.pypa.io/) | Package installer for Python | [System Setup](site:howtos/development/prepare-your-system.md) |
+| [pipx](https://pypa.github.io/pipx/) | Tool to install and run Python applications in isolated environments | [System Setup](site:howtos/development/prepare-your-system.md) |
+| [poetry](https://python-poetry.org/) | Python dependency management and packaging tool | [Tutorial](site:tutorials/creating-a-python-package.md), [Boilerplate](site:explanations/development/webapp-boilerplate.md#poetry) |
+| [poe](https://poethepoet.natn.io/) | Task runner that works well with poetry | [Tutorial](site:tutorials/creating-a-python-package.md), [Boilerplate](site:explanations/development/webapp-boilerplate.md#poe) |
<!-- markdownlint-enable MD013 -->
diff --git a/docs/libraries-tools/renovatebot.md b/docs/libraries-tools/renovatebot.md
index 6dbdc5a1032958bda45a4e8b9b634e378f0d1d20..46ed87ed5adf36022628d8cca44c5bc39135676e 100644
--- a/docs/libraries-tools/renovatebot.md
+++ b/docs/libraries-tools/renovatebot.md
@@ -5,7 +5,7 @@
The renovatebot service is **internal to DevOps** and is not offered to the wider University.
This page gives an overview of the renovatebot service. A user-focused description is available on a
-separate [explainer page](../explanations/renovatebot.md).
+separate [explainer page](site:explanations/renovatebot).
## Service Status
diff --git a/docs/reference/best-practice/ourtools.md b/docs/reference/best-practice/ourtools.md
index c9fe73f6c0f04bbede369e3abd203f4daab81288..a78996803980fceaa7759754b3e41dbc050d83e9 100644
--- a/docs/reference/best-practice/ourtools.md
+++ b/docs/reference/best-practice/ourtools.md
@@ -23,7 +23,7 @@ We host many of our databases in Google's Cloud SQL product. We have written a
scan all of our Google Cloud Projects and back any Cloud SQL databases found to
a Google Cloud Storage bucket in a central backup project.
-See [the tool's service page](../services/data-backup.md) page for more information.
+See [the tool's service page](site:services/data-backup.md) page for more information.
## Mailtrap
@@ -45,7 +45,7 @@ or [their API documentation](https://api-docs.mailtrap.io/docs/mailtrap-api-docs
!!! warning
This service is being decommissioned. Please use [Mailtrap](#mailtrap).
Mailhog may still be used as part of a docker compose environment.
- More information on this is available in the [tour of our development environment](../notes/webapp-dev-environment.md#a-tour-of-our-setup).
+ More information on this is available in the [tour of our development environment](site:notes/webapp-dev-environment.md#a-tour-of-our-setup).
For testing applications which deliver email, we have a
[Mailhog](https://github.com/mailhog/MailHog) instance
diff --git a/docs/reference/best-practice/python.md b/docs/reference/best-practice/python.md
index dae19a4ffeed4820dc2f77f064d7e052bf957577..f4a1f3bfcd1aa8a919f901d161e12258efad56bf 100644
--- a/docs/reference/best-practice/python.md
+++ b/docs/reference/best-practice/python.md
@@ -5,13 +5,13 @@ for backend work.
## Code style
-We have a number of [templates](../deployment/templates.md) which configures automated code style
+We have a number of [templates](site:reference/deployment/templates.md) which configures automated code style
checks using [flake8](https://flake8.pycqa.org/en/latest/) and
[black](https://black.readthedocs.io/en/stable/). The checks are enforced locally via pre-commit
hooks and in CI via a pre-commit job.
A step-by-step explanation of how to configure the checks added by our standard templates can be
found in the [the Python package
-tutorial](../tutorials/creating-a-python-package.md#catching-and-fixing-style-issues). A deeper
+tutorial](site:tutorials/creating-a-python-package.md#catching-and-fixing-style-issues). A deeper
explanation of other concepts like Tests, Logging, Packaging, etc, can also be found on the [same
-page](../tutorials/creating-a-python-package.md).
+page](site:tutorials/creating-a-python-package.md).
diff --git a/docs/reference/cloud-platform/dns.md b/docs/reference/cloud-platform/dns.md
index 56a9be15666248a1ee970268c2426b9603570e52..7ae951df0bf427b32ac021a8a8e8c420a4ce2734 100644
--- a/docs/reference/cloud-platform/dns.md
+++ b/docs/reference/cloud-platform/dns.md
@@ -149,7 +149,7 @@ Google Chat.
## Example - Lab Allocator
-The [Lab Allocator](../../services/lab-allocator.md) product required a custom domain. A tutorial
+The [Lab Allocator](site:services/lab-allocator.md) product required a custom domain. A tutorial
walkthrough of the process is available:
* [Tutorial: Custom DNS for Cloud Platform Service](../../tutorials/gcp-custom-dns.md)
diff --git a/docs/reference/cloud-platform/gke-gitlab-runners.md b/docs/reference/cloud-platform/gke-gitlab-runners.md
index 55f54757de468684ed0052e578d974f9ec8f54d5..719b7f962af3279c7e11f8212c1405259195bbae 100644
--- a/docs/reference/cloud-platform/gke-gitlab-runners.md
+++ b/docs/reference/cloud-platform/gke-gitlab-runners.md
@@ -74,7 +74,7 @@ configuration:
### Per-product configuration
Each product has the following resources created by the Terraform configuration (see the
-[how-to](../../howtos/gke-gitlab-runners/register-a-gke-gitlab-runner.md) for steps on adding a
+[how-to](site:howtos/gke-gitlab-runners/register-a-gke-gitlab-runner.md) for steps on adding a
product to the Terraform deployment).
- A unique Kubernetes namespace for the product's runners.
@@ -109,8 +109,8 @@ to respond to support requests or incidents:
## See also
- [How to register GKE-hosted GitLab
- runners](../../howtos/gke-gitlab-runners/register-a-gke-gitlab-runner.md)
+ runners](site:howtos/gke-gitlab-runners/register-a-gke-gitlab-runner.md)
- [How to run CI/CD jobs on a GKE-hosted GitLab
- runner](../../howtos/gke-gitlab-runners/run-ci-jobs-on-a-gke-gitlab-runner.md)
+ runner](site:howtos/gke-gitlab-runners/run-ci-jobs-on-a-gke-gitlab-runner.md)
- [How to access a Google Secret Manager secret using service account
- impersonation](../../howtos/gke-gitlab-runners/access-secrets-in-ci-jobs-using-impersonation.md)
+ impersonation](site:howtos/gke-gitlab-runners/access-secrets-in-ci-jobs-using-impersonation.md)
diff --git a/docs/reference/cloud-platform/index.md b/docs/reference/cloud-platform/index.md
index 84bed3c7facf35254e9f75408d0fea6c50c96c03..36c81beee2052af97baa50364b525c93a926897b 100644
--- a/docs/reference/cloud-platform/index.md
+++ b/docs/reference/cloud-platform/index.md
@@ -2,7 +2,7 @@
This section explains how we deploy and manage our Google Cloud Platform infrastructure. It focusses
on the core cloud components and services which lay the groundwork for our [application
-deployments](../../deployment/index.md).
+deployments](site:reference/deployment).
## Deployment overview
@@ -81,6 +81,6 @@ For more information on the configuration of these runners see [here](./gke-gitl
## Further information
The rest of the pages in this section go into more detail on the specifics of our cloud platform
-environment. However, the [how-to](../../howtos/index.md) and [tutorial](../../tutorials/index.md)
+environment. However, the [how-to](site:howtos/index.md) and [tutorial](../../tutorials)
sections are often a better place to start as they contain short, focussed, articles that are more
relevant to day-to-day tasks.
diff --git a/docs/reference/deployment/index.md b/docs/reference/deployment/index.md
index 1b9189d101d182ba95d48166979b3bb9db9ac85e..eabea1d38662930832753783d19ebfb74aa2d5f6 100644
--- a/docs/reference/deployment/index.md
+++ b/docs/reference/deployment/index.md
@@ -40,9 +40,9 @@ config](https://gitlab.developers.cam.ac.uk/uis/devops/gcp-deploy-boilerplate).
2. Create a new *webapp* repository using the
[webapp-boilerplate](https://gitlab.developers.cam.ac.uk/uis/devops/webapp-boilerplate)
copier template and push the `main` branch to a new Gitlab project.
- * Additional information on the Webapp Developer Environment can be found [here](../notes/webapp-dev-environment.md).
+ * Additional information on the Webapp Developer Environment can be found [here](site:notes/webapp-dev-environment.md).
* Pushing the `main` branch to Gitlab will ensure that the default
- [AutoDevops](../workflow/pipelines.md) CI/CD pipeline runs which builds the container image
+ [AutoDevops](site:reference/workflow/pipelines.md) CI/CD pipeline runs which builds the container image
and stores it in the Gitlab container registry. This is required by the
gcp-deploy-boilerplate.
@@ -51,7 +51,7 @@ config](https://gitlab.developers.cam.ac.uk/uis/devops/gcp-deploy-boilerplate).
copier template.
* This template generates the Terraform config required to deploy the webapp and related
* infrastructure to Google Cloud.
- * Additional information on our Terraform deployments can be found [here](../deployment/terraform.md).
+ * Additional information on our Terraform deployments can be found [here](site:reference/deployment/terraform.md).
## The 10,000 foot view
@@ -78,7 +78,7 @@ To help us meet this ideal, we strive that our deployments have the following ch
[clickops](https://www.weareaugust.co.uk/blog/killing-click-ops-what-it-is-why-its-problematic-and-how-to-avoid-it/)
when possible and carefully document it when not.
* They are consistent. We are a small team relative to the [number of
- services](../services/index.md) we run. Keeping our deployments consistent with each
+ services](site:services) we run. Keeping our deployments consistent with each
other where possible makes it easier for Engineers to move between them.
## Our standard environments
diff --git a/docs/reference/deployment/secrets.md b/docs/reference/deployment/secrets.md
index 06a264844029743d97f3b41ce4cd583224be11d4..75b523aeb56fea7bccb99e7e2b6410cd69787221 100644
--- a/docs/reference/deployment/secrets.md
+++ b/docs/reference/deployment/secrets.md
@@ -69,7 +69,7 @@ it clear which types of secret a particular technology is best at dealing with.
We make use of a team 1Password instance which can be found at
[https://uis-devops.1Password.eu/](https://uis-devops.1Password.eu/). As part of
-the [onboarding process](../workflow/onboarding.md), all team members should have a
+the [onboarding process](site:reference/workflow/onboarding.md), all team members should have a
1Password account.
!!! important
@@ -180,7 +180,7 @@ Google's [Secret Manager](https://cloud.google.com/secret-manager) is our
default choice for where secrets will need to be accessed at runtime by
applications. This is the case for most database and API credentials.
-For example, with [serverless web applications](../deployment/web-applications.md) we
+For example, with [serverless web applications](site:reference/deployment/web-applications.md) we
store Django settings in a Secret Manager secret as a YAML-formatted document.
This document is read at runtime by the web application.
@@ -250,8 +250,8 @@ To avoid sensitive values appearing in the environment, we have re-architected
our applications to load some configuration at runtime from secrets.
More information can be found in pages detailing
-[serverless](../deployment/web-applications.md) and
-[kubernetes](../deployment/k8s-clusters.md) web application deployment.
+[serverless](site:reference/deployment/web-applications.md) and
+[kubernetes](site:reference/deployment/k8s-clusters.md) web application deployment.
## Summary
diff --git a/docs/reference/deployment/sql-instances.md b/docs/reference/deployment/sql-instances.md
index a210494044921369dea63aa64534fcaf658f0a1e..1d6840df4c102b2db07509631acb8d49fe757d27 100644
--- a/docs/reference/deployment/sql-instances.md
+++ b/docs/reference/deployment/sql-instances.md
@@ -83,7 +83,7 @@ maintenance window to start at 2AM on Sunday mornings.
## "Off-site" backups
-We have [a custom tool](../services/data-backup.md) which
+We have [a custom tool](site:services/data-backup.md) which
runs nightly to backup our production databases to a Google Cloud Storage
bucket. This bucket is hosted in a Google project dedicated to this purpose. As
such we have a degree of resilience against deleting the SQL instance or the
@@ -108,7 +108,7 @@ independently from service account users. We use the term _database user_ to
mean a user created in PostgreSQL and _service account_ to mean an identity
which is created within Cloud IAM.
-Usually our [web applications](../deployment/web-applications.md) are deployed
+Usually our [web applications](site:reference/deployment/web-applications.md) are deployed
with a dedicated service account for that application. In order for the web
application to be able to use the database a separate database user must be
created for it.
@@ -158,7 +158,7 @@ account must have the [`cloudsql.client`
role](https://cloud.google.com/sql/docs/postgres/roles-and-permissions).
This role is often granted to the service account representing the [web
-application](../deployment/web-applications.md).
+application](site:reference/deployment/web-applications.md).
!!! important
@@ -174,7 +174,7 @@ application](../deployment/web-applications.md).
### Cloud Run
Cloud Run is used for [deploying web
-applications](../deployment/web-applications.md). It has native support for
+applications](site:reference/deployment/web-applications.md). It has native support for
connecting to Cloud SQL instances and causes the Cloud SQL instance to [appear
as a UNIX socket within the
container](https://cloud.google.com/sql/docs/postgres/connect-run).
@@ -186,7 +186,7 @@ is easy to create a [sidecar
container](https://docs.microsoft.com/en-us/azure/architecture/patterns/sidecar)
which runs the proxy making the instance available within the cluster. More
information is available on the [kubernetes deployment
-page](../deployment/k8s-clusters.md).
+page](site:reference/deployment/k8s-clusters.md).
## Summary
diff --git a/docs/reference/deployment/templates.md b/docs/reference/deployment/templates.md
index 60d3f70c56ca06040935c4c51939ebdebf7b53d3..d74259c1a67e05a64f0a9a966bb21a8499d4a92a 100644
--- a/docs/reference/deployment/templates.md
+++ b/docs/reference/deployment/templates.md
@@ -37,6 +37,6 @@ In the UIS DevOps Division we use Copier for two boilerplate projects:
More information on how to use Copier to perform specific tasks can be found in the following
how-to guides:
-- [Creating a new project from Copier template](../howtos/copier-create.md)
-- [Updating a project created with Copier to the newer version](../howtos/copier-update.md)
-- [Migrating a project created with Cookiecutter to Copier](../howtos/copier-migrate.md)
+- [Creating a new project from Copier template](site:howtos/development/copier/create.md)
+- [Updating a project created with Copier to the newer version](site:howtos/development/copier/update.md)
+- [Migrating a project created with Cookiecutter to Copier](site:howtos/development/copier/migrate.md)
diff --git a/docs/reference/deployment/terraform.md b/docs/reference/deployment/terraform.md
index bf2d7513d8ba7d5e9da075c1a3d557a9a4a980a7..585622d2844ecb8569c08e0cc3e775c3e505bf7c 100644
--- a/docs/reference/deployment/terraform.md
+++ b/docs/reference/deployment/terraform.md
@@ -4,7 +4,7 @@ This page discusses how we use terraform to configure our deployments.
Our standard terraform configurations assume that we have a *product folder*, *meta project*,
multiple *environment projects*, and a *product configuration* Cloud Storage bucket created for us.
-See the [Google Cloud projects and folders page](../reference/cloud-platform/gcp-folders.md) for
+See the [Google Cloud projects and folders page](site:reference/cloud-platform/gcp-folders.md) for
information on these.
A live example of a service configured using terraform is the [API Gateway
diff --git a/docs/reference/deployment/traffic-ingress.md b/docs/reference/deployment/traffic-ingress.md
index 7c455ba12cd0656b66fc397cfd824c71a1391228..5a2cc043c9b76e631d8fd39ba972fbfe318d8af4 100644
--- a/docs/reference/deployment/traffic-ingress.md
+++ b/docs/reference/deployment/traffic-ingress.md
@@ -39,7 +39,7 @@ instances.
The Cloud Run domain mapping ingress is simple to configure:
-1. Verify [a DNS domain](../reference/cloud-platform/dns.md) for the application.
+1. Verify [a DNS domain](site:reference/cloud-platform/dns.md) for the application.
2. Specify the DNS domain via our standard module's `dns_names` variable.
3. Add DNS records for that domain according to the `dns_resource_records`
output from our standard module.
diff --git a/docs/reference/deployment/web-applications.md b/docs/reference/deployment/web-applications.md
index a22020456e772b95afad355388ca6baedc78a7cc..c620d34a59d0fbf1f689ff7d9f230e9987663a81 100644
--- a/docs/reference/deployment/web-applications.md
+++ b/docs/reference/deployment/web-applications.md
@@ -90,15 +90,15 @@ This service account is granted the following permissions:
* reading the non-sensitive settings storage object.
DNS records are created for the application within the [project's DNS
-zone](../reference/cloud-platform/dns.md). TLS certificates are provisioned automatically but
+zone](site:reference/cloud-platform/dns.md). TLS certificates are provisioned automatically but
the domain must first have been
-[verified](../reference/cloud-platform/dns.md#domain-verification).
+[verified](site:reference/cloud-platform/dns.md#domain-verification).
TLS certificates will also be provisioned for any domain specified in
`local.webapp_custom_dns_name` but records will *not* be created. Usually this
local is used to host the "friendly" `.cam.ac.uk` domain for the service and
records under `.cam.ac.uk` must be created by [other
-means](../reference/cloud-platform/dns.md#domains-under-camacuk). Similarly the *project admin*
+means](site:reference/cloud-platform/dns.md#domains-under-camacuk). Similarly the *project admin*
terraform service account must be verified as an owner of the domain with
Google.
@@ -139,7 +139,7 @@ application startup delays.
### Application configuration
-To avoid [secrets](../deployment/secrets.md) appearing in the environment, we have
+To avoid [secrets](site:reference/deployment/secrets.md) appearing in the environment, we have
re-architected our applications to load some configuration at runtime. For our
Django projects, we make use of the
[externalsettings](https://gitlab.developers.cam.ac.uk/uis/devops/django/externalsettings)
diff --git a/docs/reference/misc/external-docs.md b/docs/reference/misc/external-docs.md
index 73e8b556d427e1999a5d0518121eb36fdc77747d..f55a2b7972b28929b10aa2272f37414b72036f44 100644
--- a/docs/reference/misc/external-docs.md
+++ b/docs/reference/misc/external-docs.md
@@ -5,7 +5,7 @@ This page lists some other sources of documentation outside of the guidebook.
The guidebook is intended to be the repository for all documentation
surrounding workflow, best practice and common technical standards. We may also
add specific "application notes" on technologies or techniques within the [notes
-section](notes/index.md).
+section](site:reference/notes).
It is not intended for deep operational documentation on individual services.
Generally that documentation is maintained by the individual service teams and
@@ -67,7 +67,7 @@ project for Identity.
Wider technical standards documentation is in the process of being published on
the [Technical Design Authority site](https://techdesign.uis.cam.ac.uk/). It is
-likely that some [application notes](notes/index.md) may be migrated there in
+likely that some [application notes](site:reference/notes) may be migrated there in
due course.
Information on internal UIS policies and procedures are available on the [UIS
diff --git a/docs/reference/misc/identifiers.md b/docs/reference/misc/identifiers.md
index 92bfeb6fa332ea6ec9b0cacaad1065ba13dddd4e..7e602c49c380ec79d1c72ce9039d6c49c6ceb4db 100644
--- a/docs/reference/misc/identifiers.md
+++ b/docs/reference/misc/identifiers.md
@@ -9,7 +9,7 @@ scopes may be used. Those which have been approved by the UIS Technical Design A
interoperability with systems outside of DevOps are so indicated.
There is a separate page providing an [explanation of how we use identifiers in
-DevOps](../explanations/identifiers.md).
+DevOps](site:explanations/misc/identifiers.md).
This table is generate automatically from our [identity
library](https://gitlab.developers.cam.ac.uk/uis/devops/iam/identity-lib).
diff --git a/docs/reference/misc/openapi-client-generation.md b/docs/reference/misc/openapi-client-generation.md
index cfc421e081eda17bc711a11a351d0ce3a52ce4df..451ecff81d4740179a37e6dc7f0505501a203b70 100644
--- a/docs/reference/misc/openapi-client-generation.md
+++ b/docs/reference/misc/openapi-client-generation.md
@@ -5,7 +5,7 @@ title: API client generation from OpenAPI specifications
This page provides more in-depth reference on customising the OpenAPI-based client generation
described in the [how to automatically generate API clients
-guide](../howtos/generate-api-clients.md).
+guide](site:howtos/development/generate-api-clients.md).
## Customising the generated clients
diff --git a/docs/reference/misc/tech-lead-forum.md b/docs/reference/misc/tech-lead-forum.md
index 8c21f2fc882c2e2df8858202b356a20a8060d09b..5c6a3124f9dd646be3c30000c016605989a130ff 100644
--- a/docs/reference/misc/tech-lead-forum.md
+++ b/docs/reference/misc/tech-lead-forum.md
@@ -6,7 +6,7 @@ title: The Tech Lead Forum
This page lists the purpose, the composition and the processes for the Tech Lead Forum. An
explanation of why the Tech Lead Forum exists and how it helps us is available on [a separate
-page](../standards-and-compliance/tech-lead-forum.md).
+page](site:standards-and-compliance/tech-lead-forum.md).
## Purpose
diff --git a/docs/reference/misc/webapp-developer-environment.md b/docs/reference/misc/webapp-developer-environment.md
index 6b6abc89a4fb65aa8336eb5117b766852da8f0aa..ebb6d2acb1df45e215578f4a015710ae9fc70c47 100644
--- a/docs/reference/misc/webapp-developer-environment.md
+++ b/docs/reference/misc/webapp-developer-environment.md
@@ -8,11 +8,11 @@ title: Local app development
This document describes our "new-style" developer environment. If your project has a
`compose.sh` file present in the root, look at the [original
- documentation](../notes/webapp-dev-environment.md).
+ documentation](site:notes/webapp-dev-environment.md).
This page lists common tasks which a developer may want to perform when working with our standard
webapp developer environment. Read more about the philosophy behind the design of this environment
-in our [explainer guide](../explanations/webapp-boilerplate.md).
+in our [explainer guide](site:explanations/development/webapp-boilerplate.md).
Unless otherwise stated, commands in this guide should be run from the project's root directory.
@@ -22,7 +22,7 @@ shortened to `poe ...`.
## Bootstrapping
Make sure that you have `docker`, `docker compose`, `poetry` and `poe` installed. Instructions for
-this can be found in the [guide on how-to prepare your system](../howtos/prepare-your-system.md).
+this can be found in the [guide on how-to prepare your system](site:howtos/development/prepare-your-system.md).
Install application dependencies via:
diff --git a/docs/reference/notes/automating-google-drive.md b/docs/reference/notes/automating-google-drive.md
index c333beaaff0fa0d7ed282c74802d4111e516d72f..2087a932ae7832f78a36d25cea485e6cdbecaeb4 100644
--- a/docs/reference/notes/automating-google-drive.md
+++ b/docs/reference/notes/automating-google-drive.md
@@ -180,5 +180,5 @@ applications which interact with Google Drive:
## Finding out more
The DevOps division are always happy to talk to people and share anything we’ve
-learned from our mistakes. Our [contact details](../home/contact/index.md) are
+learned from our mistakes. Our [contact details](site:home/contact) are
available elsewhere in this guidebook.
diff --git a/docs/reference/notes/gcp-deployments.md b/docs/reference/notes/gcp-deployments.md
index 473c28a76dff54c65fb83d58da7359613ea01e0c..fc526f3cec352726486ff9fdc93f3b3550829c24 100644
--- a/docs/reference/notes/gcp-deployments.md
+++ b/docs/reference/notes/gcp-deployments.md
@@ -12,7 +12,7 @@ refine our Google Cloud deployments.
!!! important
The contents of this note are covered in far greater detail in a dedicated
- [section on deployment](../deployment/index.md).
+ [section on deployment](site:reference/deployment).
We wish to offer similarly structured deployments to the UIS and wider
University in future so this standard has been created with one eye on how we
diff --git a/docs/reference/notes/google-domain-verification.md b/docs/reference/notes/google-domain-verification.md
index 0aceae2e0837f1ca31dc8029b5086ff9516f7561..0ec9e8ff3b0d3ef3bef183c7209dd6b4e61fd0e7 100644
--- a/docs/reference/notes/google-domain-verification.md
+++ b/docs/reference/notes/google-domain-verification.md
@@ -13,4 +13,4 @@ them accessible as "friendly" names under `cam.ac.uk`.
!!! important
The contents of this note have moved to our [description of deployments to
- Google Cloud](../reference/cloud-platform/dns.md).
+ Google Cloud](site:reference/cloud-platform/dns.md).
diff --git a/docs/reference/notes/ucs-dev-group-services.md b/docs/reference/notes/ucs-dev-group-services.md
index 71ebb2593292698b658d780a448fbe97ffa70449..fd471b0e67b7be3e93b868027bb8ab1b8a22d328 100644
--- a/docs/reference/notes/ucs-dev-group-services.md
+++ b/docs/reference/notes/ucs-dev-group-services.md
@@ -8,12 +8,12 @@ dev group no longer exist, responsibility for running these has been transferred
The services run by DevOps currently includes:
-* [Lookup](../services/lookup.md)
-* [Password Changing Application](../services/passwords.md)
-* [Human Tissue Tracking Application](../services/hta.md)
-* [Network Access Tokens Application](../services/eduroam-tokens.md)
-* [Streaming Media Service](../services/streaming-media.md)
-* [University Training Booking System](../services/utbs.md)
+* [Lookup](site:services/lookup.md)
+* [Password Changing Application](site:services/passwords.md)
+* [Human Tissue Tracking Application](site:services/hta.md)
+* [Network Access Tokens Application](site:services/eduroam-tokens.md)
+* [Streaming Media Service](site:services/streaming-media.md)
+* [University Training Booking System](site:services/utbs.md)
## Deploying changes to UCS development group services
@@ -25,12 +25,12 @@ The services run by DevOps currently includes:
| Application | Operating System | HA provider |
| ----------- | ---------------- | ----------- |
-| [Lookup](../services/lookup.md) | RedHat 8 | Keepalived |
-| [Password Changing Application](../services/passwords.md) | Red Hat 8 | Traffic Manager |
-| [Human Tissue Tracking Application](../services/hta.md) | Red Hat 8 | Traffic Manager |
-| [Network Access Tokens Application](../services/eduroam-tokens.md) | Red Hat 8| Traffic Manager |
-| [Streaming Media Service](../services/streaming-media.md) | SLES 11 | Manual |
-| [University Training Booking System](../services/utbs.md) | Red Hat 8 | Traffic Manager |
+| [Lookup](site:services/lookup.md) | RedHat 8 | Keepalived |
+| [Password Changing Application](site:services/passwords.md) | Red Hat 8 | Traffic Manager |
+| [Human Tissue Tracking Application](site:services/hta.md) | Red Hat 8 | Traffic Manager |
+| [Network Access Tokens Application](site:services/eduroam-tokens.md) | Red Hat 8| Traffic Manager |
+| [Streaming Media Service](site:services/streaming-media.md) | SLES 11 | Manual |
+| [University Training Booking System](site:services/utbs.md) | Red Hat 8 | Traffic Manager |
## RedHat Deployments
diff --git a/docs/reference/notes/webapp-dev-environment.md b/docs/reference/notes/webapp-dev-environment.md
index 41765e509cfaf0137fddbaa64788142690eab516..6a2c5bf08af6a5471829271c7eef0d9d72d6647b 100644
--- a/docs/reference/notes/webapp-dev-environment.md
+++ b/docs/reference/notes/webapp-dev-environment.md
@@ -4,7 +4,7 @@
This document describes an older variant of our standard webapp developer environment. If your
project does **not** include a `compose.sh` in the root, read our [newer
- guide](../reference/webapp-developer-environment.md).
+ guide](site:reference/misc/webapp-developer-environment.md).
The majority of our web applications make use of the same method to automate the
developer experience. Our aim is to get developers up an running in the shortest
diff --git a/docs/reference/workflow/flows.md b/docs/reference/workflow/flows.md
index 73919e46f5c6ea97dcbca34e14b6b4dbf9a0637a..3e52205c5f2baf0939767698af9e34e8f3adf25b 100644
--- a/docs/reference/workflow/flows.md
+++ b/docs/reference/workflow/flows.md
@@ -163,7 +163,7 @@ add an iteration to the issue using either the menu or the `/iteration` quick ac
### Creating an issue for the Cloud Team
Issues should be created using the [Issue lifecyle](gitlab.md#the-issue-lifecycle). In summary,
-issues should be [tagged](../reference/gitlab-labels.md#labels-in-gitlab)
+issues should be [tagged](site:reference/git-gitlab/gitlab-labels.md#labels-in-gitlab)
with `workflow: Need Refinement` and `team: Cloud`. Do not add an iteration at this point. During our
refinement session, we will use [our refinement queue](https://gitlab.developers.cam.ac.uk/groups/uis/devops/-/issues/?sort=updated_desc&state=opened&label_name%5B%5D=team%3A%3ACloud&label_name%5B%5D=workflow%3A%3ANeeds%20Refinement&iteration_id=None&first_page_size=100)
to see these ticket, refine, and move to `sprint ready`.
diff --git a/docs/reference/workflow/gitlab.md b/docs/reference/workflow/gitlab.md
index 949cd2b4c8d10ebec4ea9113dab2ca2e5f92b80c..05631d659d850ac0d44dbe82a9667c82f4c28b25 100644
--- a/docs/reference/workflow/gitlab.md
+++ b/docs/reference/workflow/gitlab.md
@@ -166,7 +166,7 @@ the issue is refined.
### Needs sizing
There is a weekly opportunity for team members to help sizing issues. The process for sizing issues
-is described in a dedicated [how-to guide](../howtos/size-issues.md).
+is described in a dedicated [how-to guide](site:howtos/git-gitlab/size-issues.md).
Once sized and refined, an issue gets the "workflow::sprint ready" label.
@@ -203,7 +203,7 @@ the assignee.
### Review required and Needs deployment
!!! info
- This section has moved to [a dedicated page](../explanations/reviewing-issues.md).
+ This section has moved to [a dedicated page](site:explanations/git-gitlab/reviewing-issues.md).
### Rework
@@ -229,7 +229,7 @@ intention to complete, the "resolution::DevNotPlanned" label can also be applied
## Labels
!!! note
- This section has moved to a [separate page](../reference/gitlab-labels.md).
+ This section has moved to a [separate page](site:reference/git-gitlab/gitlab-labels.md).
## Groups and projects
diff --git a/docs/reference/workflow/pypi.md b/docs/reference/workflow/pypi.md
index aa3aa1367c6eba159155c1816d8f1c47c5021f44..486dd0a0ec13fc7f8a8fbfe4b5a32aa65709d468 100644
--- a/docs/reference/workflow/pypi.md
+++ b/docs/reference/workflow/pypi.md
@@ -19,10 +19,10 @@ Task-focussed and reference documentation for creating and publishing Python
packages can be found in the following places:
* [How to add the common pipeline to a Python
- project](../howtos/add-common-pipeline-to-python.md)
+ project](site:howtos/python/add-common-pipeline-to-python.md)
* [How to make a new release of a Python
- package](../howtos/publish-a-python-package.md)
-* [How to create PyPI API tokens](../howtos/pypi.md)
+ package](site:howtos/python/publish-a-python-package.md)
+* [How to create PyPI API tokens](site:howtos/python/pypi.md)
* [Reference
documentation](https://gitlab.developers.cam.ac.uk/uis/devops/continuous-delivery/ci-templates/-/blob/master/auto-devops/python.md)
for the Python-specific portions of the common CI/CD pipeline
@@ -67,7 +67,7 @@ project we're releasing but we can't *select* that scope until we've published
the project.
We have to do a bit of token gymnastics to get around this issue. As documented
-in the [how-to guide](../howtos/pypi.md), we firstly create a temporary token
+in the [how-to guide](site:howtos/python/pypi.md), we firstly create a temporary token
with the ability to work with *all* projects. This scope is required to create
*new* projects which will happen implicitly on the first release.
@@ -93,4 +93,4 @@ project for the first time. You should include:
* where to find out more, for example a link to any API documentation.
Include a `LICENSE.txt` file. See [how to add the MIT licence to a
-project](../howtos/add-the-mit-licence.md) for more.
+project](site:howtos/git-gitlab/add-the-mit-licence.md) for more.
diff --git a/docs/services/caias.md b/docs/services/caias.md
index 76f4f0c22b703cfddabbccf800b7808b00068fd4..a69142dbb8517a8ce3d3bca74f5b25587f9493c6 100644
--- a/docs/services/caias.md
+++ b/docs/services/caias.md
@@ -80,7 +80,7 @@ pipeline](https://gitlab.developers.cam.ac.uk/uis/devops/continuous-delivery/ci-
### Deploying a new release
Making a new release of the application is done via [release
-automation](../explanations/gitlab-release-automation.md). In short: each commit to the web app's main
+automation](site:explanations/git-gitlab/gitlab-release-automation.md). In short: each commit to the web app's main
branch builds and pushes a Docker image to GCR. An MR can then be raised within the infrastructure
repository to deploy a given image by SHA. Once merged, the main GitLab pipeline will allow deployment
to production via the "play" buttons in the CI pipeline. An automated deployment to staging will be
diff --git a/docs/services/data-backup.md b/docs/services/data-backup.md
index 51c16df04c5ba9e9661e68c193ee8a20bf581121..659c13885c7b9a8b1883c3ba64292abe88a39937 100644
--- a/docs/services/data-backup.md
+++ b/docs/services/data-backup.md
@@ -82,7 +82,7 @@ pipeline](https://gitlab.developers.cam.ac.uk/uis/devops/continuous-delivery/ci-
### Deploying a new release
Making a new release of the application is done via [release
-automation](../explanations/gitlab-release-automation.md). In short: merged commits are collected
+automation](site:explanations/git-gitlab/gitlab-release-automation.md). In short: merged commits are collected
together into a draft "next release" Merge Request. When merged, a new release tag is pushed to the
repository along with a Docker image being pushed to Google's Artefact registry.
diff --git a/docs/services/integrated-reward-system.md b/docs/services/integrated-reward-system.md
index d2eda23f29e068bd92ec406b9946a4d18743df46..8f03fbaad451aba894e9adc6b3afa2a5a3cd56fe 100644
--- a/docs/services/integrated-reward-system.md
+++ b/docs/services/integrated-reward-system.md
@@ -100,7 +100,7 @@ pipeline](https://gitlab.developers.cam.ac.uk/uis/devops/continuous-delivery/ci-
### Deploying a new release
Making a new release of the application is done via [release
-automation](../explanations/gitlab-release-automation.md).
+automation](site:explanations/git-gitlab/gitlab-release-automation.md).
Deployment is done by:
diff --git a/docs/services/job-opportunities.md b/docs/services/job-opportunities.md
index b8e6eea640987808333c2745f7e7d151bace3232..c9cbf45e26c0e8100cb2303a6ed6495e0a5b5887 100644
--- a/docs/services/job-opportunities.md
+++ b/docs/services/job-opportunities.md
@@ -62,7 +62,7 @@ pipeline](https://gitlab.developers.cam.ac.uk/uis/devops/continuous-delivery/ci-
### Deploying a new release
Making a new release of the application is done via [release
-automation](../explanations/gitlab-release-automation.md). In short: each commit to the web app's main
+automation](site:explanations/git-gitlab/gitlab-release-automation.md). In short: each commit to the web app's main
branch builds and pushes a Docker image to GCR. An MR can then be raised within the infrastructure
repository to deploy a given image by SHA. Once merged, the main GitLab pipeline will allow deployment
to production via the "play" buttons in the CI pipeline. An automated deployment to staging will be
diff --git a/docs/services/lookup-gitlab-sync.md b/docs/services/lookup-gitlab-sync.md
index e10df537f9d087876e802b3ba54f7a1f793ada35..7feebaa5f9ecd0aacd5c62d839f4e9253db27134 100644
--- a/docs/services/lookup-gitlab-sync.md
+++ b/docs/services/lookup-gitlab-sync.md
@@ -69,7 +69,7 @@ pipeline](https://gitlab.developers.cam.ac.uk/uis/devops/continuous-delivery/ci-
### Deploying a new release
Making a new release of the application is done via [release
-automation](../explanations/gitlab-release-automation.md). In short: merged commits are collected
+automation](site:explanations/git-gitlab/gitlab-release-automation.md). In short: merged commits are collected
together into a draft "next release" Merge Request. When merged, a new release tag is pushed to the
repository along with a Docker image being pushed to Google's Artefact registry.
diff --git a/docs/services/postbox.md b/docs/services/postbox.md
index 7ee5e0d916e554b48601bd4bc4a8d753f64d3a62..494f118e60d0a388e9891499fff925bb2bfc3097 100644
--- a/docs/services/postbox.md
+++ b/docs/services/postbox.md
@@ -68,7 +68,7 @@ pipeline](https://gitlab.developers.cam.ac.uk/uis/devops/continuous-delivery/ci-
### Deploying a new release
Making a new release of the application is done via [release
-automation](../explanations/gitlab-release-automation.md). In short: each commit to the web app's main
+automation](site:explanations/git-gitlab/gitlab-release-automation.md). In short: each commit to the web app's main
branch builds and pushes a Docker image to GCR. An MR can then be raised within the infrastructure
repository to deploy a given image by SHA. Once merged, the main GitLab pipeline will allow deployment
to production via the "play" buttons in the CI pipeline. An automated deployment to staging will be
diff --git a/docs/services/regent-house-ballots.md b/docs/services/regent-house-ballots.md
index 356aa420d1a0a5fefd7df5b3d1cf55525903ab37..c9c192b01aebef1e6e616a8f95da57c3f3abfc65 100644
--- a/docs/services/regent-house-ballots.md
+++ b/docs/services/regent-house-ballots.md
@@ -29,7 +29,7 @@ The Region House Ballots app is currently in early user testing.
## Contact
-Technical queries and support should be directed as per our [contact page](../home/contact/index.md).
+Technical queries and support should be directed as per our [contact page](site:home/contact).
Issues discovered in the *functionality* of service or new feature requests should be opened as
GitLab issues in the [application
@@ -125,7 +125,7 @@ pipeline](https://gitlab.developers.cam.ac.uk/uis/devops/continuous-delivery/ci-
### Deploying a new release
Making a new release of the application is done via [release
-automation](../explanations/gitlab-release-automation.md). In short: merged commits are collected
+automation](site:explanations/git-gitlab/gitlab-release-automation.md). In short: merged commits are collected
together into a draft "next release" Merge Request. When merged, a new release tag is pushed to the
repository along with a Docker image being pushed to Google's Artefact registry.
diff --git a/docs/snippets/log-incident.md b/docs/snippets/log-incident.md
index 0c4c47db1bfee4fa2936665457a7ce2c397b548f..1b58779f0ddf5ebbd032e2b52e9854eaca5fe3d5 100644
--- a/docs/snippets/log-incident.md
+++ b/docs/snippets/log-incident.md
@@ -1,5 +1,5 @@
<!-- markdownlint-disable MD041 -->
??? tip "Log an Incident"
To **log/escalate an incident**, **report a bug** or **submit a feature request**,
- follow the instructions on [our contact page](/home/contact/index.md).
+ follow the instructions on [our contact pagesite:home/contact).
<!-- markdownlint-enable MD041 -->
diff --git a/docs/standards-and-compliance/change-management.md b/docs/standards-and-compliance/change-management.md
index 683317db7baa6dd8791f27bf5da4f0a3c9bc3be3..a177a07ff386331b1042b197a47a8c96b15a4c81 100644
--- a/docs/standards-and-compliance/change-management.md
+++ b/docs/standards-and-compliance/change-management.md
@@ -275,7 +275,7 @@ version of the software deployed to our staging environment will be bit-for-bit
subsequently deployed to production.
Our release management process has recently been
-completely [automated](../explanations/gitlab-release-automation.md). Now, as changes are merged
+completely [automated](site:explanations/git-gitlab/gitlab-release-automation.md). Now, as changes are merged
in GitLab, a “next release†Merge Request is maintained automatically. Once approved and merged,
this will automatically generate a Changelog, build and test a packaged version of the software and
upload it to Google Cloud ready for deployment.
@@ -560,13 +560,13 @@ DevOps change management best practices described in this document.
Those interested in more details of our workflows, processes and use of technology may find the
following pages from our guidebook useful.
-- [DevOps’ approach to release automation](../explanations/gitlab-release-automation.md).
-- [The use of GitLab labels for project management](../reference/gitlab-labels.md).
+- [DevOps’ approach to release automation](site:explanations/git-gitlab/gitlab-release-automation.md).
+- [The use of GitLab labels for project management](site:reference/git-gitlab/gitlab-labels.md).
- [DevOps’ culture and values](../environment/culture.md).
-- [How we encourage peer review of changes](../explanations/reviewing-issues.md).
-- [Day-to-day working in DevOps](../workflow/flows.md).
-- [The lifecycle of a feature in GitLab](../workflow/gitlab.md).
-- [Technical process for proposing and integrating changes](../workflow/merge-requests.md).
-- [The use in DevOps of terraform for deployment automation](../deployment/terraform.md).
+- [How we encourage peer review of changes](site:explanations/git-gitlab/reviewing-issues.md).
+- [Day-to-day working in DevOps](site:reference/workflow/flows.md).
+- [The lifecycle of a feature in GitLab](site:reference/workflow/gitlab.md).
+- [Technical process for proposing and integrating changes](site:reference/workflow/merge-requests.md).
+- [The use in DevOps of terraform for deployment automation](site:reference/deployment/terraform.md).
- [A tutorial on creating a Python package which demonstrates some of DevOps’ automated quality
assurance processes](https://gitlab.com/gitlab-org/gitlab/-/issues/31575).
diff --git a/docs/standards-and-compliance/devsecops-cd.md b/docs/standards-and-compliance/devsecops-cd.md
index 0fe2d6d7ff4a8d2feac18083d058382da1cbee27..63b5d439b3b71451d3b4e45fa5844453329d2a3b 100644
--- a/docs/standards-and-compliance/devsecops-cd.md
+++ b/docs/standards-and-compliance/devsecops-cd.md
@@ -237,7 +237,7 @@ As mentioned above, generally we synchronise a service's required secrets from 1
secret objects *before* we initiate a deployment. This allows us to configure task-specific service
accounts with the required secret accessor role to be able to read secret values at runtime. Many of
Google Cloud’s resources support this workflow, for
-example [Cloud Run](https://cloud.google.com/run/docs/configuring/services/secrets##access-secret)
+example [Cloud Run](https://cloud.google.com/run/docs/configurisite:services/secrets##access-secret)
and [Cloud Functions](https://cloud.google.com/functions/docs/configuring/secrets).
##### Environment variables
@@ -290,8 +290,8 @@ configure’s GitLab pipeline jobs with a Google IAM identity. This gives us the
job’s identity access to specific GSM secret objects allowing us to access the secret value at
runtime. This removes the need to store secrets in GitLab’s CI/CD variables which is a potential
security risk and something which we want to avoid. The guidebook has some useful guides
-on [how to run CI/CD jobs on a GKE-hosted runner](https://guidebook.devops.uis.cam.ac.uk/en/latest/howtos/gke-gitlab-runners/run-ci-jobs-on-a-gke-gitlab-runner/)
-and [how to access a GSM secret value using service account impersonation in a CI/CD job](https://guidebook.devops.uis.cam.ac.uk/en/latest/howtos/gke-gitlab-runners/access-secrets-in-ci-jobs-using-impersonation/).
+on [how to run CI/CD jobs on a GKE-hosted runner](https://guidebook.devops.uis.cam.ac.uk/en/latesite:howtos/gke-gitlab-runners/run-ci-jobs-on-a-gke-gitlab-runner/)
+and [how to access a GSM secret value using service account impersonation in a CI/CD job](https://guidebook.devops.uis.cam.ac.uk/en/latesite:howtos/gke-gitlab-runners/access-secrets-in-ci-jobs-using-impersonation/).
#### Secrets in Terraform
diff --git a/docs/standards-and-compliance/devsecops-cicd.md b/docs/standards-and-compliance/devsecops-cicd.md
index f77c18bc9858be209a245ca728dc3a665d0f052e..ce8520853a9363ff54b2b23cfa62330f91e900ef 100644
--- a/docs/standards-and-compliance/devsecops-cicd.md
+++ b/docs/standards-and-compliance/devsecops-cicd.md
@@ -29,8 +29,8 @@ they exist, for example, by generating templates that are compatible with multip
This document describes CI/CD standards at a high-level. Specifics and implementation details may be
found elsewhere. For
-example, [our guidebook has a page on how to add CI/CD to a Python project](../howtos/add-common-pipeline-to-python.md)
-and [a page on configuring release automation via CI/CD](../howtos/enable-automated-gitlab-releases.md).
+example, [our guidebook has a page on how to add CI/CD to a Python project](site:howtos/python/add-common-pipeline-to-python.md)
+and [a page on configuring release automation via CI/CD](site:howtos/git-gitlab/enable-automated-gitlab-releases.md).
Our existing [web application](https://gitlab.developers.cam.ac.uk/uis/devops/webapp-boilerplate/)
and [terraform deployment](https://gitlab.developers.cam.ac.uk/uis/devops/gcp-deploy-boilerplate)
boilerplates already include the standards described below.
@@ -74,7 +74,7 @@ have deployed to an environment can be seen in the “Environments†tab in Git
<figcaption markdown>
Figure taken from our
-Guidebook [tutorial on creating a Python package](../tutorials/creating-a-python-package.md).
+Guidebook [tutorial on creating a Python package](site:tutorials/creating-a-python-package.md).
</figcaption>
</figure>
@@ -101,7 +101,7 @@ using many of the workflows below, they are:
has the correct configuration and is secure.
For a more detailed explanation on our Google Cloud standards see
-the [Cloud Platform](https://guidebook.devops.uis.cam.ac.uk/en/latest/reference/cloud-platform/)
+the [Cloud Platform](https://guidebook.devops.uis.cam.ac.uk/en/latesite:reference/cloud-platform/)
section in the Guidebook.
## GitLab Auto-DevOps
diff --git a/docs/standards-and-compliance/devsecops-dev.md b/docs/standards-and-compliance/devsecops-dev.md
index 48602cc1dcdd86a71194f3458b9a166f33db1ea7..ec578e34da49c228dec2e6e3c277be907c09a2e4 100644
--- a/docs/standards-and-compliance/devsecops-dev.md
+++ b/docs/standards-and-compliance/devsecops-dev.md
@@ -72,7 +72,7 @@ each software component. In this case, we tend to use a version identifier assig
called the commit SHA. For the purposes of this document, the commit SHA is considered to act like a
version number. The version number of a deployment uniquely identifies both the way that the
components are deployed and the components themselves. For deployments which
-use [GitLab’s inbuilt automation to deploy](../explanations/gitlab-release-automation.md), once
+use [GitLab’s inbuilt automation to deploy](site:explanations/git-gitlab/gitlab-release-automation.md), once
changes from a MR are merged track which version is deployed to each of the production, staging and
development environments. This information is available from a dedicated “environments†page in
GitLab.
@@ -115,7 +115,7 @@ Request (MR) which should contains the following information:
* the changes they wish to make, split into separately reviewable chunks known as *commits*,
* a description of each commit which [focuses on the *why* rather than the
- *what* of the change](../explanations/git.md#commits), and
+ *what* of the change](site:explanations/git-gitlab/git.md#commits), and
* an overall description of the change which may make reference to existing *issues* which describe
the agreed objectives of the change.
@@ -137,7 +137,7 @@ GitLab allows automated tasks to be triggered when changes are merged or propose
are called *continuous integration (CI) pipelines*. We have a common pipeline configuration which
runs a number of security-related tasks, most of them inherited from GitLab’s AutoDevOps.
-Some processes below require the [common CI pipeline](../howtos/add-common-pipeline-to-python.md)
+Some processes below require the [common CI pipeline](site:howtos/python/add-common-pipeline-to-python.md)
be enabled for repositories and to
follow [Continuous Integration and Continuous Delivery (CI/CD) standards](./devsecops-cicd.md).
@@ -212,7 +212,7 @@ and applied, if deemed necessary, periodically.
Our goal of being able to state with confidence whether a given deployed environment of a service
contains a given vulnerability requires that we be consistent in how we release, version and package
our software. UIS DevOps has developed
-a [release automation](../tutorials/automating-gitlab-releases.md) process which takes away much
+a [release automation](site:tutorials/automating-gitlab-releases.md) process which takes away much
of the manual process of versioning new releases. This removes opportunities for human error. All
services must adopt this practice.
@@ -388,7 +388,7 @@ recently we have had no way of enforcing it; GitLab project creation and configu
process.
We have
-now [automated the provisioning of GitLab projects](../howtos/bootstrap-a-product.md#create-the-gitlab-projects)
+now [automated the provisioning of GitLab projects](site:howtos/products/bootstrap-a-product.md#create-the-gitlab-projects)
and have begun importing existing projects into this automation. This allows us to centralise and
standardise the configuration of GitLab projects. **At a minimum GitLab projects are now created
with mandatory MR approval and branch protection.** Deviations from this policy are detected and
diff --git a/docs/standards-and-compliance/non-functional-requirements/availability.md b/docs/standards-and-compliance/non-functional-requirements/availability.md
index 69ce887f83ccdecea844b16a940dea19e27d6906..4980ffd764c3def06c87bf7da41be54beb825a38 100644
--- a/docs/standards-and-compliance/non-functional-requirements/availability.md
+++ b/docs/standards-and-compliance/non-functional-requirements/availability.md
@@ -44,7 +44,7 @@ system, etc.) and is multi-zonal. See
Backups are performed daily. Backups can be used to recover state to datastores
in the event of ransomware attack from before the point off attack. See
-[Data Backup Service](../../services/data-backup.md).
+[Data Backup Service](site:services/data-backup.md).
DevOps change practices are followed:
<https://docs.google.com/document/d/1tGIYU-11l7G7byz1IZw-mhDHjJMPRnS_rIrAX5esyTM/edit?usp=sharing>.
diff --git a/docs/standards-and-compliance/tech-lead-forum.md b/docs/standards-and-compliance/tech-lead-forum.md
index c50a8773060b62ad32000d5f05275833ef1d143f..1154bcb2e509ca6737285eebeb79d5c3e71e1436 100644
--- a/docs/standards-and-compliance/tech-lead-forum.md
+++ b/docs/standards-and-compliance/tech-lead-forum.md
@@ -21,7 +21,7 @@ delivery. The forum is then born with the goal of continue to follow and promote
division when more coordination is required due of its size and complexity.
The Tech Lead Forum is defined in formal language by its [terms of
-reference](../reference/tech-lead-forum.md).
+reference](site:reference/misc/tech-lead-forum.md).
## Standards and recommendations
@@ -58,4 +58,4 @@ guidebook.
## Read more
-* [Tech Lead Forum Terms of Reference](../reference/tech-lead-forum.md).
+* [Tech Lead Forum Terms of Reference](site:reference/misc/tech-lead-forum.md).
diff --git a/docs/tutorials/automating-gitlab-releases.md b/docs/tutorials/automating-gitlab-releases.md
index 9b59139e09537d3a7f3615ca8a7a07d3d0f375c5..89a7a89939592d08bf0e88d33312f744f51c777a 100644
--- a/docs/tutorials/automating-gitlab-releases.md
+++ b/docs/tutorials/automating-gitlab-releases.md
@@ -18,7 +18,7 @@ available workflows.
[gitlab-runner-infrastructure](https://gitlab.developers.cam.ac.uk/uis/devops/devhub/gitlab-runner-infrastructure)
Terraform configuration.
- You must have followed the steps in [How to enable automated GitLab
- releases](../howtos/enable-automated-gitlab-releases.md) to enable the release
+ releases](site:howtos/git-gitlab/enable-automated-gitlab-releases.md) to enable the release
pipeline and create a `.release-it.json` config file in your repository.
## Default workflow
@@ -26,7 +26,7 @@ available workflows.
The default workflow for the `release-it.yml` GitLab template is based on the
[Conventional Commit](https://www.conventionalcommits.org/en/v1.0.0/)
specification, as recommended in the [Git
-Commits](../explanations/git.md#commits) section of this guidebook. Each time
+Commits](site:explanations/git-gitlab/git.md#commits) section of this guidebook. Each time
commits are merged to the default branch the `release` job analyses each new
commit message and determines what the next version of the code should be.
@@ -59,7 +59,7 @@ release for your project.
job in the triggered pipeline. This job will invoke the `release-it` command
to perform the tasks configured in your project's `.release-it.json` config
file. If you used the example `.release-it.json` file from the [Enable
- automated GitLab releases](../howtos/enable-automated-gitlab-releases.md)
+ automated GitLab releases](site:howtos/git-gitlab/enable-automated-gitlab-releases.md)
how-to, the following tasks will be performed.
- Calculate the next version of your project based on the commit messages
@@ -73,7 +73,7 @@ release for your project.
## Alternate workflow
The `release-it.yml` GitLab template has an [alternate
-workflow](../explanations/gitlab-release-automation.md#alternate-workflow) mode
+workflow](site:explanations/git-gitlab/gitlab-release-automation.md#alternate-workflow) mode
which queues unreleased changes in a draft release merge request.
The following steps show you how to use this workflow to create a new minor
@@ -176,5 +176,5 @@ bug in the original version `1.0.0` code you could do the following.
## See also
For more information on how this process works see the [GitLab release
-automation](../explanations/gitlab-release-automation.md) page in the
+automation](site:explanations/git-gitlab/gitlab-release-automation.md) page in the
Explanations section.
diff --git a/docs/tutorials/bootstrapping-a-new-application.md b/docs/tutorials/bootstrapping-a-new-application.md
index 842dece6f1aca39650058e0dc4713d0a306419d9..98e9ea27cfc9f189014f940d7ef29939b8823743 100644
--- a/docs/tutorials/bootstrapping-a-new-application.md
+++ b/docs/tutorials/bootstrapping-a-new-application.md
@@ -27,15 +27,15 @@ indicated.
You may also be interested in the following sections after reading the tutorial:
* How to:
- * [create a new application](../howtos/create-a-new-app.md),
- * [run applications locally](../howtos/run-an-existing-app.md),
+ * [create a new application](site:howtos/development/create-a-new-app.md),
+ * [run applications locally](site:howtos/development/run-an-existing-app.md),
* [register Google Cloud-hosted GitLab
- runners](../howtos/gke-gitlab-runners/register-a-gke-gitlab-runner.md), and
- * [run database migrations at deploy-time](../howtos/run-database-migrations-when-deploying.md).
-* [Learn about our webapp boilerplate](../explanations/webapp-boilerplate.md).
+ runners](site:howtos/gke-gitlab-runners/register-a-gke-gitlab-runner.md), and
+ * [run database migrations at deploy-time](site:howtos/development/run-database-migrations-when-deploying.md).
+* [Learn about our webapp boilerplate](site:explanations/development/webapp-boilerplate.md).
* Reference guides:
- * [local application development](../reference/webapp-developer-environment.md), and
- * [terraform deployment](../deployment/index.md).
+ * [local application development](site:reference/misc/webapp-developer-environment.md), and
+ * [terraform deployment](site:reference/deployment).
## The general plan
@@ -55,7 +55,7 @@ requests.
As of November 2023 the most recent version of our development and deployment process is as follows:
* Releases are managed using our [release automation CI
- template](../explanations/gitlab-release-automation.md). As features/fixes are merged, a Merge
+ template](site:explanations/git-gitlab/gitlab-release-automation.md). As features/fixes are merged, a Merge
Request representing the "next" release is automatically maintained. Merging this Merge Request
causes a new release to be made. See, as an example, [the 0.7.0 release Merge
Request](https://gitlab.developers.cam.ac.uk/uis/devops/regent-house-ballots/ballots-webapp/-/merge_requests/6).
@@ -69,7 +69,7 @@ pipeline](https://gitlab.developers.cam.ac.uk/uis/devops/regent-house-ballots/ba
* Releases of the web application code itself are versioned using semantic versioning. The version
number is present in the `pyproject.toml` file and is automatically incremented by the release
automation.
-* [Conventional commits](../explanations/git.md#commits) are used to indicate which commits add new
+* [Conventional commits](site:explanations/git-gitlab/git.md#commits) are used to indicate which commits add new
features, fix bugs or introduce backwards compatibility changes necessitating a new major version.
* The [terraform configuration for
deployment](https://gitlab.developers.cam.ac.uk/uis/devops/regent-house-ballots/infrastructure)
@@ -120,7 +120,7 @@ purpose of the application, b) it being a webapp and so belonging under .apps.ca
being a cross-University application.
DNS within the University is a complex topic. There is a [dedicated section of this
-guidebook](../reference/cloud-platform/dns.md) devoted to it.
+guidebook](site:reference/cloud-platform/dns.md) devoted to it.
### Creating GitLab runners
diff --git a/docs/tutorials/creating-a-python-package.md b/docs/tutorials/creating-a-python-package.md
index cb68331d8d37036b86571fbc2fb9baea1f8d3f45..f14c545e20d17d60ca2a86e80fe638fed308b155 100644
--- a/docs/tutorials/creating-a-python-package.md
+++ b/docs/tutorials/creating-a-python-package.md
@@ -1695,7 +1695,7 @@ tests.
We're happy with our project now. Let's publish it.
We have a dedicated [how-to document for publishing
-packages](../howtos/publish-a-python-package.md) but the short version is: "we
+packages](site:howtos/python/publish-a-python-package.md) but the short version is: "we
publish packages when we tag a commit".
Do this now by creating a tag with the same name as the package version:
diff --git a/docs/tutorials/gcp-custom-dns.md b/docs/tutorials/gcp-custom-dns.md
index dc515687ed0fe826ad9749873e726444806df9b0..12416ab2f881aaceecb54110f85bfeacef6976a5 100644
--- a/docs/tutorials/gcp-custom-dns.md
+++ b/docs/tutorials/gcp-custom-dns.md
@@ -4,12 +4,12 @@ title: Custom DNS for Cloud Platform Service
# Custom DNS for Cloud Platform Service
-We have a [Cloud Platform DNS](../reference/cloud-platform/dns.md) guide, which gives an overview of
+We have a [Cloud Platform DNS](site:reference/cloud-platform/dns.md) guide, which gives an overview of
the different aspects of DNS that can be used as part of the Cloud Platform. This doesn't go into
the specifics of setting up a custom domain for a GCP service, however.
In this tutorial, we'll walk through a recent implementation of a custom domain for the
-[Lab Allocator](../services/lab-allocator.md) product.
+[Lab Allocator](site:services/lab-allocator.md) product.
These were the requirements for the custom domain:
@@ -26,7 +26,7 @@ Therefore, the custom domain would be `laballocator.apps.cam.ac.uk`, which needs
In order to use a custom DNS name using the standard UIS [GCP Deploy Boilerplate](https://gitlab.developers.cam.ac.uk/uis/devops/gcp-deploy-boilerplate),
the web app DNS must be verified.
-Following [Domain verification instructions](../reference/cloud-platform/dns.md#domain-verification):
+Following [Domain verification instructions](site:reference/cloud-platform/dns.md#domain-verification):
e.g.:
```console
diff --git a/mkdocs.yml b/mkdocs.yml
index 32168d192221bb222789524943cd5c050e40bda1..de84a93b0123cd0cc812db7dee15cd9f2ed50125 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -145,9 +145,9 @@ nav:
- howtos/development/prepare-your-system.md
- howtos/development/create-a-new-app.md
- howtos/development/setup-pre-commit-hooks.md
- - howtos/development/copier-create.md
- - howtos/development/copier-update.md
- - howtos/development/copier-migrate.md
+ - howtos/development/copier/create.md
+ - howtos/development/copier/update.md
+ - howtos/development/copier/migrate.md
- howtos/development/run-an-existing-app.md
- howtos/development/configure-your-ide.md
- howtos/development/run-database-migrations-when-deploying.md