FAQ | This is a LIVE service | Changelog

Skip to content
Snippets Groups Projects

Compare revisions

Changes are shown as if the source revision was being merged into the target revision. Learn more about comparing revisions.

Source

Select target project
No results found

Target

Select target project
  • uis/devops/docs/guidebook
  • rjw57/guidebook
  • psh35/guidebook
  • jt654/guidebook
  • kf412/guidebook
  • jpk28/guidebook
  • meh37/guidebook
  • hwtb2/guidebook
8 results
Show changes
Commits on Source (120)
20 additional commits have been omitted to prevent performance issues.
Hide whitespace changes
Inline Side-by-side
Showing
with 601 additions and 101 deletions
.flake8 0 → 100644
View file @ b0d6f128
[flake8]
max-line-length=99
exclude = venv,.tox
# Ignore E203, see explanation here:
# https://black.readthedocs.io/en/stable/guides/using_black_with_other_tools.html#id1
# E702 relates to newer flake8s having a difference of opinion on how formatting strings should be
# formatted.
extend-ignore = E203, E702
.git-blame-ignore-revs 0 → 100644
View file @ b0d6f128
# ignore changes applied via flake8 and black
f029e56e71fe28e5039f52a654743c76d386e07d
.gitlab-ci.yml
View file @ b0d6f128
......@@ -39,6 +39,8 @@ test:
expose_as: "Browse the documentation for this MR by following links to public and index html"
paths:
- public/
variables:
SITE_URL: "https://uis.uniofcam.dev/-/devops/docs/guidebook/-/jobs/${CI_JOB_ID}/artifacts/public"
markdownlint:
stage: test
......@@ -59,6 +61,7 @@ pages:
extends: test
stage: production
script:
- unset SITE_URL # SITE_URL is only used in the test job & inherited from there.
- mkdocs build --strict --verbose --site-dir public
# Expose services.yml for consumption by other apps/services.
- mkdir -p public/api
......
.pre-commit-config.yaml
View file @ b0d6f128
......@@ -26,8 +26,18 @@ repos:
- repo: https://github.com/DavidAnson/markdownlint-cli2
# Keep this version number in sync with the one in .gitlab-ci.yml
rev: v0.14.0
rev: v0.17.2
hooks:
- id: markdownlint-cli2
args: ["--fix"]
language_version: 22.10.0
- repo: https://github.com/psf/black
rev: 25.1.0
hooks:
- id: black
- repo: https://github.com/pycqa/flake8
rev: 7.1.2
hooks:
- id: flake8
README.md
View file @ b0d6f128
......@@ -3,7 +3,14 @@
This repository contains the source for the UIS
[DevOps Guidebook](https://guidebook.devops.uis.cam.ac.uk/)
## Developing locally
## Hosting
The guidebook is hosted via GitLab pages and is automatically deployed on each commit to master. To
support a custom domain, the ``guidebook.devops.uis.cam.ac.uk`` DNS record is a CNAME pointing to
``uis.uniofcam.dev.io`` following the [custom domain
documentation](https://docs.gitlab.com/ee/user/project/pages/custom_domains_ssl_tls_certification/).
## Local Development
The guidebook uses mkdocs to convert Markdown source into a static website.
You can run it from either the dockerised setup or your own local environment.
......@@ -19,25 +26,86 @@ pre-commit install
Start the guidebook via:
```console
docker-compose up
docker-compose up --build
```
The local documentation is now available at <http://localhost:8000/>.
### Configuring git to ignore bulk source formatting changes
To ignore the bulk formatting changes introduced by the additional of `black` and `flake8`
a `.git-blame-ignore-revs` has been added with the commit SHAs to ignore. To use:
```text
git config blame.ignoreRevsFile .git-blame-ignore-revs
```
### Adding a page
1. Create a Markdown file in the relevant directory under `docs`.
2. Add this file's path to the `nav` configuration in `mkdocs.yml`.
## Hosting
## Service Information
The guidebook is hosted via GitLab pages. readthedocs.org (RTD) and is automatically deployed on
each commit to master. The GitLab pages-managed URL is at
[https://uis.uniofcam.dev/devops/docs/guidebook/](https://uis.uniofcam.dev/devops/docs/guidebook/).
Service & team information is encoded in [services.yml](./data/services.yml).
To support a custom domain, the ``guidebook.devops.uis.cam.ac.uk`` DNS record is a CNAME pointing to
``uis.uniofcam.dev.io`` following the [custom domain
documentation](https://docs.gitlab.com/ee/user/project/pages/custom_domains_ssl_tls_certification/).
When adding or updating a Service page, you must update that file to define such information.
Comments in the file itself describe each section's format.
The file is exposed at endpoint `/api/services.yml` for consumption by other apps/services,
via a script in the [Gitlab CI config](./.gitlab-ci.yml).
**NOTE:**
* The canonical source of DevOps teams and team-service mappings is
[this Google Doc][devops-team-structure].
* This YAML configuration simply encodes the information in a machine-parsable format,
and must be manually updated to remain in-sync with that document.
## Site-Relative URLs
Site-relative URLs can be specified using `site:path/to/some-page`.
This functionality is provided by a custom [hook][mkdocs-hooks]
in [hooks/site_urls.py](./hooks/site_urls.py)
These are preferable to relative URLs, since:
* A page containing `site:` URLs needn't change if it's relocated.
* Whereas, a page containing relative URLs would need all of them updated.
* A page referenced by `site:` URLs can be relocated,
then a single search-and-replace performed to update all references.
* Whereas, a page referenced by different relative URLs
requires that they all be updated, and each becomes defferent.
Such `site:` urls are translated as follows,
depending on whether the code is running locally or in Gitlab CI,
where flag `--no-directory-urls` is passed to `mkdocs build`:
<!-- markdownlint-disable MD013 -->
| Example `site:` URL | Doc Path | Local URL | CI Artifact URL<br>with `--no-directory-urls` |
| -------------------- | ---------------------- | ---------------- | --------------------------------------------- |
| `site:path/to/page` | `docs/path/to/page.md` | `/path/to/page/` | `$SITE_ROOT/path/to/page.html` |
| `site:path/to/page/` | `docs/path/to/page.md` | `/path/to/page/` | `$SITE_ROOT/path/to/page/index.html` |
<!-- markdownlint-enable MD013 -->
## Custom Plugin Syntax
Some MkDocs extensions & plugins used (see [mkdocs.base.yml][mkdocs-config-base])
provide custom syntax to utilise their new visual elements.
Here's a summary of the custom syntax we utilise, provided by our configured extensions & plugins:
<!-- markdownlint-disable MD013 -->
| Extension / Plugin | Notation | Meaning |
| ------------------------------------------------ | --------------------------------------------------- | ----------------------------------------------------------- |
| [Admonitions][mkdocs-plugin-admonitions] | `!!! note`, `??? tip`, etc. | A styled callout, which may be collapsible |
| [PymdownX > Snippets][mkdocs-plugin-snippets] | `--8<-- "path/to/file.(md\|ext)"` | Insert contents of the specified file. |
| [Neoteroi > Cards][mkdocs-plugin-neoteroi-cards] | `[cards cols=2 smaller(path/to/cards.(json\|yml))]` | Insert the visual cards defined in specified file. |
| Site-Relative URLs _(see section below)_ | `site:path/to/some-page` | Site-relative URL (in our case `docs/path/to/some-page.md`) |
<!-- markdownlint-enable MD013 -->
## Macros
......@@ -90,24 +158,11 @@ any needed context-specific HTML rendering _(see existing examples there)_.
Your macro(s) will then be available within all `.md` files as `{{ my_macro(..args..) }}`.
## Service Information
Service & team information is encoded in [services.yml](./data/services.yml).
When adding or updating a Service, you must update that file to define such information.
Comments in the file itself describe each section's format.
The file is exposed at endpoint `/api/services.yml` for consumption by other apps/services,
via a script in the [Gitlab CI config](./.gitlab-ci.yml).
**NOTE:**
* The canonical source of DevOps teams and team-service mappings is
[this Google Doc][devops-team-structure].
* This YAML configuration simply encodes the information in a machine-parsable format,
and must be manually updated to remain in-sync with that document.
<!-- markdownlint-disable MD013 -->
[devops-team-structure]: https://docs.google.com/document/d/1fNkYa5z0vY44aStN_67BjoAn8VJN8mvHhX-iip1y25g/edit#heading=h.gb6gzxjsa2r2
[mkdocs-plugin-admonitions]: https://squidfunk.github.io/mkdocs-material/reference/admonitions/
[mkdocs-config-base]: ./mkdocs.base.yml
[mkdocs-hooks]: https://www.mkdocs.org/user-guide/configuration/#hooks
[mkdocs-plugin-neoteroi-cards]: https://www.neoteroi.dev/mkdocs-plugins/cards/
[mkdocs-plugin-snippets]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/
<!-- markdownlint-enable MD013 -->
data/README.md
View file @ b0d6f128
......@@ -12,6 +12,7 @@ generated using the following command line which uses
<!-- markdownlint-disable MD013 -->
```sh
http "https://gitlab.developers.cam.ac.uk/api/v4/groups/uis%2Fdevops/labels?per_page=100" "PRIVATE-TOKEN:$TOKEN" | yq eval -P > labels.yml
http "https://gitlab.developers.cam.ac.uk/api/v4/groups/uis%2Fdevops/labels?per_page=100&page=2" "PRIVATE-TOKEN:$TOKEN" | yq eval -P >> labels.yml
```
<!-- markdownlint-enable MD013 -->
......
data/labels.yml
View file @ b0d6f128
......@@ -23,14 +23,21 @@
name: Comms Required
description: Communication required to release feature
description_html: Communication required to release feature
text_color: '#333333'
text_color: '#1F1E24'
color: '#f3edb3'
subscribed: false
- id: 7049
name: communal-benefit
description: Issues which are of benefit to multiple teams but the direct responsibility of none. All teams should consider these issues in sprint planning.
description_html: Issues which are of benefit to multiple teams but the direct responsibility of none. All teams should consider these issues in sprint planning.
text_color: '#1F1E24'
color: '#8fbc8f'
subscribed: false
- id: 993
name: dependency
description: ""
description_html: ""
text_color: '#333333'
text_color: '#FFFFFF'
color: '#A295D6'
subscribed: false
- id: 541
......@@ -58,7 +65,7 @@
name: discussion
description: Issues which primarily contain or require a discussion rather than a task
description_html: Issues which primarily contain or require a discussion rather than a task
text_color: '#333333'
text_color: '#FFFFFF'
color: '#A295D6'
subscribed: false
- id: 2493
......@@ -96,13 +103,41 @@
text_color: '#FFFFFF'
color: '#33b3a6'
subscribed: false
- id: 7087
name: GAP
description: null
description_html: ""
text_color: '#FFFFFF'
color: '#36454f'
subscribed: false
- id: 1224
name: good first issue
description: ""
description_html: ""
text_color: '#FFFFFF'
text_color: '#1F1E24'
color: '#F0AD4E'
subscribed: false
- id: 7281
name: HR Integration
description: HR Integration Application
description_html: HR Integration Application
text_color: '#FFFFFF'
color: '#36454f'
subscribed: false
- id: 7273
name: HR RHEL6 migration
description: ""
description_html: ""
text_color: '#FFFFFF'
color: '#36454f'
subscribed: false
- id: 7200
name: incident-remedial
description: Work derived from past incidents (e.g. degradation of service) that aims to help avoid future incidents. This can be both symptom/short term geared, like improving SQL queries efficiency of an API call or root cause/long term geared, like reporting SQL queries stats or load tests.
description_html: Work derived from past incidents (e.g. degradation of service) that aims to help avoid future incidents. This can be both symptom/short term geared, like improving SQL queries efficiency of an API call or root cause/long term geared, like reporting SQL queries stats or load tests.
text_color: '#FFFFFF'
color: '#6699cc'
subscribed: false
- id: 1146
name: incomplete
description: Issue is incomplete and needs its description improving
......@@ -110,13 +145,27 @@
text_color: '#FFFFFF'
color: '#FF0000'
subscribed: false
- id: 7276
name: IRS
description: Integrated Reward System Product
description_html: Integrated Reward System Product
text_color: '#FFFFFF'
color: '#36454f'
subscribed: false
- id: 2686
name: issueType::Bug
name: issuetype::Bug
description: Functionality of product is not as designed or intended by the code author
description_html: Functionality of product is not as designed or intended by the code author
text_color: '#FFFFFF'
color: '#c21e56'
subscribed: false
- id: 6503
name: issuetype::Dashboard
description: Dashboard issues are used to display information regarding multiple projects. They are intended to be regularly updated via a bot or other automation.
description_html: Dashboard issues are used to display information regarding multiple projects. They are intended to be regularly updated via a bot or other automation.
text_color: '#FFFFFF'
color: '#9b59b6'
subscribed: false
- id: 4859
name: issuetype::Epic
description: null
......@@ -131,6 +180,27 @@
text_color: '#FFFFFF'
color: '#cc338b'
subscribed: false
- id: 7767
name: issuetype::Incident
description: ""
description_html: ""
text_color: '#FFFFFF'
color: '#00b140'
subscribed: false
- id: 7699
name: issuetype::Maintenance
description: ""
description_html: ""
text_color: '#FFFFFF'
color: '#9400d3'
subscribed: false
- id: 6872
name: issuetype::SubTask
description: ""
description_html: ""
text_color: '#FFFFFF'
color: '#00b140'
subscribed: false
- id: 5538
name: issuetype::Support
description: ""
......@@ -177,21 +247,21 @@
name: meeting::backlog refinement
description: ""
description_html: ""
text_color: '#FFFFFF'
color: '#eee600'
text_color: '#1F1E24'
color: '#fff600'
subscribed: false
- id: 5024
name: meeting::sprint planning
description: ""
description_html: ""
text_color: '#FFFFFF'
color: '#eee600'
text_color: '#1F1E24'
color: '#fff600'
subscribed: false
- id: 5705
name: mob programming
description: This issue is intended for "mob programming" team effort (https://en.wikipedia.org/wiki/Mob_programming)
description_html: This issue is intended for "mob programming" team effort (<a href="https://en.wikipedia.org/wiki/Mob_programming" rel="nofollow noreferrer noopener" target="_blank">https://en.wikipedia.org/wiki/Mob_programming</a>)
text_color: '#FFFFFF'
text_color: '#1F1E24'
color: '#8fbc8f'
subscribed: false
- id: 2295
......@@ -201,6 +271,13 @@
text_color: '#FFFFFF'
color: '#36454f'
subscribed: false
- id: 7884
name: mvp
description: Work that is required for a first release or minimum-viable-product version of an application of service.
description_html: Work that is required for a first release or minimum-viable-product version of an application of service.
text_color: '#FFFFFF'
color: '#9400d3'
subscribed: false
- id: 2230
name: Operations
description: Issues which relate to deployment or packaging of products
......@@ -215,6 +292,62 @@
text_color: '#FFFFFF'
color: '#5843AD'
subscribed: false
- id: 8065
name: planning::Discovery
description: For epics that need additional content and context in the description before being moved to refinement.
description_html: For epics that need additional content and context in the description before being moved to refinement.
text_color: '#1F1E24'
color: '#e6e6fa'
subscribed: false
- id: 8070
name: planning::In Sprint
description: Epics which are being currently worked on in a sprint.
description_html: Epics which are being currently worked on in a sprint.
text_color: '#1F1E24'
color: '#8fbc8f'
subscribed: false
- id: 8069
name: planning::Needs Issues
description: Epics which need issues written and sized before they are added to a sprint.
description_html: Epics which need issues written and sized before they are added to a sprint.
text_color: '#FFFFFF'
color: '#808080'
subscribed: false
- id: 8066
name: planning::Needs Refinement
description: Epics which are ready to and need to be refined.
description_html: Epics which are ready to and need to be refined.
text_color: '#1F1E24'
color: '#eee600'
subscribed: false
- id: 8068
name: planning::Proposed
description: Epics which are intended or planned to be added in to the next sprint.
description_html: Epics which are intended or planned to be added in to the next sprint.
text_color: '#FFFFFF'
color: '#6699cc'
subscribed: false
- id: 8072
name: planning::Reviewed
description: Epics which are completed.
description_html: Epics which are completed.
text_color: '#FFFFFF'
color: '#36454f'
subscribed: false
- id: 8067
name: planning::Sprint Ready
description: Epics which are ready to be added to a sprint (e.g. have validated acceptance criteria and t-shirt size).
description_html: Epics which are ready to be added to a sprint (e.g. have validated acceptance criteria and t-shirt size).
text_color: '#FFFFFF'
color: '#cd5b45'
subscribed: false
- id: 8071
name: planning::Work Complete
description: Epics which are completed, and believed to be ready to close.
description_html: Epics which are completed, and believed to be ready to close.
text_color: '#FFFFFF'
color: '#cc338b'
subscribed: false
- id: 2929
name: Pooled Testing
description: null
......@@ -222,6 +355,13 @@
text_color: '#FFFFFF'
color: '#36454f'
subscribed: false
- id: 7881
name: post release
description: null
description_html: ""
text_color: '#FFFFFF'
color: '#cd5b45'
subscribed: false
- id: 4882
name: priority::0 Highest
description: null
......@@ -240,15 +380,15 @@
name: priority::2 Medium
description: null
description_html: ""
text_color: '#FFFFFF'
text_color: '#1F1E24'
color: '#F0AD4E'
subscribed: false
- id: 2461
name: priority::3 Low
description: null
description: ""
description_html: ""
text_color: '#FFFFFF'
color: '#D1D100'
text_color: '#1F1E24'
color: '#fffe00'
subscribed: false
- id: 2739
name: priority::4 Lowest
......@@ -268,9 +408,16 @@
name: quick to review
description: Issues whose MRs are small changes or which are otherwise easy to review
description_html: Issues whose MRs are small changes or which are otherwise easy to review
text_color: '#333333'
text_color: '#1F1E24'
color: '#A8D695'
subscribed: false
- id: 7278
name: RAS
description: Recruitment Administration System
description_html: Recruitment Administration System
text_color: '#FFFFFF'
color: '#36454f'
subscribed: false
- id: 4633
name: 'resolution:: Can''t Reproduce'
description: Can't reproduce the bug/issue
......@@ -299,6 +446,13 @@
text_color: '#FFFFFF'
color: '#c21e56'
subscribed: false
- id: 7870
name: resolution::Subsumed
description: Ticket subsumed into existing ticket.
description_html: Ticket subsumed into existing ticket.
text_color: '#FFFFFF'
color: '#c21e56'
subscribed: false
- id: 1216
name: 'resolution:: Won''t Fix'
description: Not actually a bug or beyond a reasonable to fix
......@@ -306,6 +460,20 @@
text_color: '#FFFFFF'
color: '#c21e56'
subscribed: false
- id: 7311
name: RGEA
description: ""
description_html: ""
text_color: '#FFFFFF'
color: '#36454f'
subscribed: false
- id: 7272
name: RHEL6 Migration
description: RHEL6 Migration Project
description_html: RHEL6 Migration Project
text_color: '#FFFFFF'
color: '#330066'
subscribed: false
- id: 6118
name: Service Wrapper
description: null
......@@ -313,6 +481,48 @@
text_color: '#FFFFFF'
color: '#6699cc'
subscribed: false
- id: 7369
name: size::L
description: Used for t-shirt sizing epics or tickets.
description_html: Used for t-shirt sizing epics or tickets.
text_color: '#FFFFFF'
color: '#ed9121'
subscribed: false
- id: 7368
name: size::M
description: Used for t-shirt sizing epics or tickets.
description_html: Used for t-shirt sizing epics or tickets.
text_color: '#1F1E24'
color: '#eee600'
subscribed: false
- id: 7367
name: size::S
description: Used for t-shirt sizing epics or tickets.
description_html: Used for t-shirt sizing epics or tickets.
text_color: '#1F1E24'
color: '#8fbc8f'
subscribed: false
- id: 7370
name: size::XL
description: Used for t-shirt sizing epics or tickets.
description_html: Used for t-shirt sizing epics or tickets.
text_color: '#FFFFFF'
color: '#c21e56'
subscribed: false
- id: 7366
name: size::XS
description: Used for t-shirt sizing epics or tickets.
description_html: Used for t-shirt sizing epics or tickets.
text_color: '#FFFFFF'
color: '#009966'
subscribed: false
- id: 7371
name: size::XXL
description: Used for t-shirt sizing epics or tickets.
description_html: Used for t-shirt sizing epics or tickets.
text_color: '#FFFFFF'
color: '#dc143c'
subscribed: false
- id: 148
name: small change
description: ""
......@@ -320,12 +530,33 @@
text_color: '#FFFFFF'
color: '#8E44AD'
subscribed: false
- id: 7772
name: SMS
description: 'Product: SMS'
description_html: 'Product: SMS'
text_color: '#FFFFFF'
color: '#36454f'
subscribed: false
- id: 6871
name: source::Jira
description: Tickets transferred from the UIS Jira Cloud instance.
description_html: Tickets transferred from the UIS Jira Cloud instance.
text_color: '#1F1E24'
color: '#e6e6fa'
subscribed: false
- id: 991
name: spike
description: Tasks which are time-boxed to one day
description_html: Tasks which are time-boxed to one day
description: Tasks which are time-boxed to one day, or the value set in estimate or weight
description_html: Tasks which are time-boxed to one day, or the value set in estimate or weight
text_color: '#FFFFFF'
color: '#0033CC'
color: '#0033cc'
subscribed: false
- id: 6942
name: stretch-goal
description: Issues that should only be picked up when all other actionable issues in the sprint are complete
description_html: Issues that should only be picked up when all other actionable issues in the sprint are complete
text_color: '#1F1E24'
color: '#8fbc8f'
subscribed: false
- id: 2378
name: Support
......@@ -348,6 +579,13 @@
text_color: '#FFFFFF'
color: '#330066'
subscribed: false
- id: 8109
name: team::Developer Experience
description: Issues assigned to Developer Experience
description_html: Issues assigned to Developer Experience
text_color: '#FFFFFF'
color: '#330066'
subscribed: false
- id: 2928
name: team::DevOps
description: Issues which are likely to be picked up by the DevOps team
......@@ -355,6 +593,27 @@
text_color: '#FFFFFF'
color: '#330066'
subscribed: false
- id: 6943
name: team::Drupal
description: ""
description_html: ""
text_color: '#FFFFFF'
color: '#330066'
subscribed: false
- id: 6919
name: team::Hamilton
description: ""
description_html: ""
text_color: '#FFFFFF'
color: '#330066'
subscribed: false
- id: 6870
name: team::Holberton
description: Tickets assigned to the Holberton team.
description_html: Tickets assigned to the Holberton team.
text_color: '#FFFFFF'
color: '#330066'
subscribed: false
- id: 4587
name: team::Identity
description: null
......@@ -362,6 +621,48 @@
text_color: '#FFFFFF'
color: '#330066'
subscribed: false
- id: 6938
name: team::Jackson
description: ""
description_html: ""
text_color: '#FFFFFF'
color: '#330066'
subscribed: false
- id: 7940
name: team::Johnson
description: ""
description_html: ""
text_color: '#FFFFFF'
color: '#330066'
subscribed: false
- id: 7068
name: team::Lovelace
description: ""
description_html: ""
text_color: '#FFFFFF'
color: '#330066'
subscribed: false
- id: 7067
name: Tech documentation
description: To distinguish documentation that needs to be done by developers from documentation done by a supporting function
description_html: To distinguish documentation that needs to be done by developers from documentation done by a supporting function
text_color: '#FFFFFF'
color: '#25acb6'
subscribed: false
- id: 7279
name: TES
description: Temporary Employment Service
description_html: Temporary Employment Service
text_color: '#FFFFFF'
color: '#36454f'
subscribed: false
- id: 7280
name: TES Timesheet
description: Temporary Employment Service - Timesheet Entry
description_html: Temporary Employment Service - Timesheet Entry
text_color: '#FFFFFF'
color: '#36454f'
subscribed: false
- id: 2381
name: Testing
description: Issues which involve automated or manual testing as the primary aim
......@@ -376,6 +677,13 @@
text_color: '#FFFFFF'
color: '#0033CC'
subscribed: false
- id: 7414
name: University Payment System
description: ""
description_html: ""
text_color: '#FFFFFF'
color: '#36454f'
subscribed: false
- id: 706
name: urgent
description: ""
......@@ -395,15 +703,22 @@
description: 'Issues which require research into user experience '
description_html: 'Issues which require research into user experience '
text_color: '#FFFFFF'
color: '#0033CC'
color: '#9400d3'
subscribed: false
- id: 6406
name: Wack-a-mole Wednesday
description: To flag issues suitable for a day blitz
description_html: To flag issues suitable for a day blitz
text_color: '#333333'
text_color: '#1F1E24'
color: '#ffeb44'
subscribed: false
- id: 6974
name: workflow::Backlog
description: Issues which have been refined and are ready to be worked on
description_html: Issues which have been refined and are ready to be worked on
text_color: '#FFFFFF'
color: '#9400d3'
subscribed: false
- id: 5512
name: workflow::BAU Blocked
description: BAU work which has stalled due to external ussue
......@@ -418,6 +733,13 @@
text_color: '#FFFFFF'
color: '#ff0000'
subscribed: false
- id: 6710
name: workflow::Discovery
description: More information is needed before the issue can be refined
description_html: More information is needed before the issue can be refined
text_color: '#FFFFFF'
color: '#9999ff'
subscribed: false
- id: 4824
name: workflow::Done
description: Issue meets the Definition of Done
......@@ -425,6 +747,13 @@
text_color: '#FFFFFF'
color: '#009966'
subscribed: false
- id: 6931
name: workflow::Draft
description: To flag draft issues that have not been completed yet
description_html: To flag draft issues that have not been completed yet
text_color: '#FFFFFF'
color: '#9999ff'
subscribed: false
- id: 150
name: workflow::In Progress
description: Currently under development
......@@ -457,27 +786,48 @@
name: workflow::Needs Sizing
description: An issue that has been refined but needs an estimate on how long it will take in order to meet the Definition of Ready
description_html: An issue that has been refined but needs an estimate on how long it will take in order to meet the Definition of Ready
text_color: '#333333'
text_color: '#1F1E24'
color: '#f7e7ce'
subscribed: false
- id: 7681
name: workflow::Needs testing
description: ""
description_html: ""
text_color: '#1F1E24'
color: '#fff0c7'
subscribed: false
- id: 81
name: workflow::Review Required
description: This MR is ready to be reviewed by another developer.
description_html: This MR is ready to be reviewed by another developer.
text_color: '#FFFFFF'
text_color: '#1F1E24'
color: '#69D100'
subscribed: false
- id: 83
name: workflow::Rework
description: There are issues with this MR which need resolving
description_html: There are issues with this MR which need resolving
text_color: '#FFFFFF'
color: '#eee600'
text_color: '#1F1E24'
color: '#fff600'
subscribed: false
- id: 1600
name: workflow::Sprint Ready
description: Meets the Definition of Ready
description_html: Meets the Definition of Ready
text_color: '#FFFFFF'
text_color: '#1F1E24'
color: '#F0AD4E'
subscribed: false
- id: 7193
name: workflow::Under Review
description: Issue has been picked up by a reviewer, and is currently being reviewed.
description_html: Issue has been picked up by a reviewer, and is currently being reviewed.
text_color: '#FFFFFF'
color: '#cc338b'
subscribed: false
- id: 7277
name: WRS
description: Web Recruitment System
description_html: Web Recruitment System
text_color: '#FFFFFF'
color: '#36454f'
subscribed: false
data/services.yml
View file @ b0d6f128
......@@ -150,7 +150,8 @@ services:
- wilson
ada:
category: business
portfolio: business
category: other
title: ADA for Disability Office
service-owner: meh37
teams:
......@@ -212,7 +213,7 @@ services:
teams:
- johnson
covid-pooled-testing:
covid-pooled-testing: # retired
category: other
title: Covid-19 Testing Pools Management
service-owner: jh535
......@@ -471,7 +472,7 @@ services:
- ek599
- db947
lecture-capture-preferences:
lecture-capture-preferences: # retired
category: teaching
title: Lecture Capture Preferences App
teams:
......@@ -548,7 +549,8 @@ services:
- pfk22
nursery-waiting-list:
category: generic
portfolio: business
category: hr
title: Nursery Waiting List
tech-lead: meh37
teams:
......@@ -579,7 +581,7 @@ services:
- sdw37
postbox:
category: hr
category: recruitment
title: PostBox
service-manager: ajc322
tech-lead: wgd23
......@@ -726,7 +728,7 @@ services:
engineers:
- sdw37
roo-intranet:
roo-intranet: # retired
category: research
title: ROO Intranet
tech-lead: meh37
......@@ -783,7 +785,7 @@ services:
engineers:
- mh2215
streaming-media:
streaming-media: # retired
category: cloud
title: Streaming Media Service
service-owner: amc203
......@@ -820,6 +822,7 @@ services:
- wgd23
time-allocation-survey:
portfolio: business
category: hr
title: Time Allocation Survey
tech-lead: nb745
......
docs/cards/diataxis/cards.yml 0 → 100644
View file @ b0d6f128
- title: |
[Tutorials](site:tutorials/)
content: |
<img class="dtx" src="site:cards/diataxis/img/tutorials.jpg" alt="Tutorials">
<a href="https://diataxis.fr/tutorials/">
<span class="dtx-pill dtx-pill-need"><b>Learning</b></span>
</a>
<span class="dtx-pill">&#61;</span>
<span class="dtx-pill dtx-pill-skill dtx-pill-skill1"><b>Acquisition</b></span>
<span class="dtx-pill">&#43;</span>
<span class="dtx-pill dtx-pill-skill dtx-pill-skill2"><b>Action</b></span>
<h4 class="dtx">Learn to create & configure specific features & resources.</h4>
<h6 class="dtx">e.g. <i>"How do I add automated releasing to my Python library?"</i></h6>
- title: |
[How-To's](site:howtos/)
content: |
<img class="dtx" src="site:cards/diataxis/img/howtos.jpg" alt="How-To's">
<a href="https://diataxis.fr/how-to-guides/">
<span class="dtx-pill dtx-pill-need"><b>Goals</b></span>
</a>
<span class="dtx-pill dtx-pill">&#61;</span>
<span class="dtx-pill dtx-pill-skill dtx-pill-skill1"><b>Action</b></span>
<span class="dtx-pill dtx-pill">&#43;</span>
<span class="dtx-pill dtx-pill-skill dtx-pill-skill2"><b>Application</b></span>
<h4 class="dtx">Guided examples of common workflows.</h4>
<h6 class="dtx">e.g. <i>"Walk me through making a new Python library?"</i></h6>
- title: |
[Explanations](site:explanations/)
content: |
<img class="dtx" src="site:cards/diataxis/img/explanations.jpg" alt="Explanations">
<a href="https://diataxis.fr/explanation/">
<span class="dtx-pill dtx-pill-need"><b>Understanding</b></span>
</a>
<span class="dtx-pill">&#61;</span>
<span class="dtx-pill dtx-pill-skill dtx-pill-skill1"><b>Acquisition</b></span>
<span class="dtx-pill">&#43;</span>
<span class="dtx-pill dtx-pill-skill dtx-pill-skill2"><b>Cognition</b></span>
<h4 class="dtx">Our mechanisms & the motivations behind them.</h4>
<h6 class="dtx">e.g. <i>"Why do we use Poetry for packaging?"</i></h6>
- title: |
[Reference](site:reference/)
content: |
<img class="dtx" src="site:cards/diataxis/img/reference.png" alt="Reference">
<a href="https://diataxis.fr/reference/">
<span class="dtx-pill dtx-pill-need"><b>Information</b></span>
</a>
<span class="dtx-pill">&#61;</span>
<span class="dtx-pill dtx-pill-skill dtx-pill-skill1"><b>Cognition</b></span>
<span class="dtx-pill">&#43;</span>
<span class="dtx-pill dtx-pill-skill dtx-pill-skill2"><b>Application</b></span>
<h4 class="dtx">Codex for specific information.</h4>
<h6 class="dtx">e.g. <i>"What Python library do we use to implement REST APIs in Django apps?"</i></h6>
docs/cards/diataxis/img/explanations.jpg 0 → 100644
View file @ b0d6f128
docs/cards/diataxis/img/explanations.jpg

300 KiB

docs/cards/diataxis/img/howtos.jpg 0 → 100644
View file @ b0d6f128
docs/cards/diataxis/img/howtos.jpg

111 KiB

docs/cards/diataxis/img/reference.png 0 → 100644
View file @ b0d6f128
docs/cards/diataxis/img/reference.png

35.3 KiB

docs/cards/diataxis/img/tutorials.jpg 0 → 100644
View file @ b0d6f128
docs/cards/diataxis/img/tutorials.jpg

260 KiB

docs/explanations/aws.md → docs/explanations/cloud-platform/aws.md
View file @ b0d6f128
......@@ -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) if all you want to do is add AWS
integration to your product.
## Why we would use AWS
......@@ -26,7 +26,8 @@ settled on the following design aims:
cannot be rotated automatically,
- to avoid maintaining a parallel set of roles, make use of the existing Google Cloud permissions
model when possible, and
- preserve our existing [permissions model](./google-cloud-permissions-model.md):
- preserve our existing
[permissions model](site:explanations/cloud-platform/google-cloud-permissions-model):
- allow existing "editor" users to access the AWS console and `aws` CLI tool, and
- allow existing "deploy" users to be able to seamlessly manage AWS and Google Cloud resources
within the same terraform configuration.
......@@ -67,7 +68,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) 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,8 +95,8 @@ 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
process in depth.
later date. The [how-to guide on creating AWS accounts](site:howtos/aws/create-aws-accounts)
covers the process in depth.
## User and Role management within AWS
......@@ -150,16 +151,16 @@ 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
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
process
[AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html).
In the [AWS how-to guide](site:howtos/aws/get-started-with-aws) 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 process [AssumeRoleWithWebIdentity](
https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html).
Within the trust policy we require an audience claim which matches the Amazon Resource Name (ARN) of
the IAM Role itself. Again, this is a method to ensure that an identity token intended for assuming
a particular role can't be reused to assume a different one.
Within the trust policy we require an audience claim which matches the Amazon Resource Name (ARN)
of the IAM Role itself. Again, this is a method to ensure that an identity token intended
for assuming a particular role can't be reused to assume a different one.
The use of OIDC identity tokens meets another design aim of not requiring additional credentials: a
sufficiently privileged `...@gcloudadmin.g.apps.cam.ac.uk` user can obtain AWS credentials through
......@@ -181,7 +182,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) 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 +224,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).
The token is then used with the AWS terraform provider to assume the TerraformDeploy role:
......@@ -251,7 +252,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) 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 +277,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).
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).
## Summary
......@@ -307,7 +308,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)
- [How to access the AWS console](site:howtos/aws/access-aws-console)
- [How to audit access to the AWS console](site:howtos/aws/audit-aws-console-access)
- [How to use the `aws` CLI tool](site:howtos/aws/use-aws-cli)
docs/explanations/azure-and-entra-id-apps.md → docs/explanations/cloud-platform/azure-and-entra-id-apps.md
View file @ b0d6f128
......@@ -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).
## 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)
* [How to add sign in to a web application](site:howtos/entra-azure/add-sso-sign-in)
docs/explanations/gcloudadmin-accounts.md → docs/explanations/cloud-platform/gcloudadmin-accounts.md
View file @ b0d6f128
# Google Cloud admin accounts
As noted in the [checklist for products](../howtos/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)
As noted in the [checklist for products](site:howtos/products/check-product-configuration),
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)
and given a Google account of the form `{crsid}@gcloudadmin.g.apps.cam.ac.uk`.
This document contains specific guidance for team members about this account. We use the term
......@@ -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).
docs/explanations/gcp-budgets-alerts.md → docs/explanations/cloud-platform/gcp-budgets-alerts.md
View file @ b0d6f128
......@@ -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).
## 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)
for information on how to handle these alerts when they're triggered.
### Tags/labels
......@@ -76,7 +76,7 @@ example product's meta project.</figcaption>
## 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)
[^1]:
Our reseller, TI Sparkle (or just Sparkle), is an Italian company which is
......
docs/explanations/gcp-cloud-run-app-module.md → docs/explanations/cloud-platform/gcp-cloud-run-app-module.md
View file @ b0d6f128
......@@ -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),
......@@ -97,13 +97,15 @@ https://gitlab.developers.cam.ac.uk/uis/devops/infra/terraform/gcp-cloud-run-app
```
- `sql_instance_connection_name`: has been changed to `mount_cloudsql_instance`.
- `disable_monitoring`: has been renamed to `enable_monitoring` and the new default behaviour is to
disable monitoring.
- `environment_variables`: now this variable is not declared at the top level. Instead, each
container in `containers` map has an `env` key with a list of maps (see example above).
- `allowed_ingress`: changed to `ingress`. The ingress setting for the Cloud Run service.
Possible values are `INGRESS_TRAFFIC_ALL`, `INGRESS_TRAFFIC_INTERNAL_ONLY`, and
`INGRESS_TRAFFIC_INTERNAL_LOAD_BALANCER`. If variable `use_load_balancer` is set to `true`,
the provided `ingress` value will be ignored and the ingress will be set automatically to
`INGRESS_TRAFFIC_INTERNAL_LOAD_BALANCER``.
`INGRESS_TRAFFIC_INTERNAL_LOAD_BALANCER`.
- `alert_notification_channels`: has been changed to `alerting_notification_channels`.
### Deleted features
......@@ -115,6 +117,12 @@ https://cloud.google.com/run/docs/mapping-custom-domains#run) and it's been in t
a very long time. Besides that, it has a number of limitations, such as limited availability across
GCP regions, [latency issues](https://cloud.google.com/run/docs/issues#latency-domains) and more.
If you were using Domain mapping it is likely the CloudRun instance was located in a different
region to of the other cloud resources, hence the variable `cloud_run_region`. This migration will
move the CloudRun instance to the same region as the other cloud resources. Note, the region is
included in the automatically assign URLs, i.e. `https://webapp-xxxxxxxxxx.europe-west2.run.app`.
The change to these URLs can impact integrations with other services, for example the API Gateway.
### Other changes
The previous major release, `8.0.0`, introduced the `enable_pre_deploy_job` variable which,
......
docs/explanations/gke-gitlab-runners.md → docs/explanations/cloud-platform/gke-gitlab-runners.md
View file @ b0d6f128
......@@ -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)
- [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)
- [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)
docs/explanations/google-cloud-permissions-model.md → docs/explanations/cloud-platform/google-cloud-permissions-model.md
View file @ b0d6f128
......@@ -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)
- [The explainer guide on our service infrastructure](./service-infrastructure.md)