Skip to content

Commit 12bb44a

Browse files
anthony-nhsanthony-nhs
committed
update readme
1 parent ef41771 commit 12bb44a

1 file changed

Lines changed: 56 additions & 55 deletions

File tree

‎README.md‎

Lines changed: 56 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -5,20 +5,21 @@ EPS DEV CONTAINERS
55
- [Introduction](#introduction)
66
- [Using the images](#using-the-images)
77
- [Project setup](#project-setup)
8-
- [Getting image name and version in GitHub Actions](#getting-image-name-and-version-in-github-actions)
8+
- [Getting image name and version in GitHub Actions from local config](#getting-image-name-and-version-in-github-actions)
99
- [Using images in GitHub Actions](#using-images-in-github-actions)
10-
- [Using local or pull request images in Visual Studio Code](#using-local-or-pull-request-images-in-visual-studio-code)
10+
- [Using local or pull request images in Visual Studio Code and GitHub Actions](#using-local-or-pull-request-images-in-visual-studio-code-and-github-actions)
11+
- [Common Makefile targets](#common-makefile-targets)
12+
- [Defined Targets](#targets)
13+
1114
- [Project structure](#project-structure)
1215
- [Pull requests and merge to main process](#pull-requests-and-merge-to-main-process)
1316
- [Release workflow](#release-workflow)
1417
- [Local testing](#local-testing)
1518
- [Building images](#building-images)
1619
- [Scanning images](#scanning-images)
1720
- [Interactive shell on image](#interactive-shell-on-image)
18-
- [Generating a .trivyignore file](#generating-a-trivyignore-file)
19-
- [Cleaning up unused container images](#cleaning-up-unused-container-images)
20-
- [Common Makefile targets](#common-makefile-targets)
21-
- [Targets](#targets)
21+
- [Generating a .trivyignore file](#generating-a-trivyignore-file)
22+
- [Cleaning up unused container images](#cleaning-up-unused-container-images)
2223

2324
# Introduction
2425
This repository contains code to build VS Code devcontainers that can be used as a base image for all EPS projects.
@@ -156,12 +157,58 @@ It is important that:
156157
- there is `options: --user 1001:1001 --group-add 128` below image to ensure it uses the correct user id and is added to the docker group
157158
- the default shell is set to be bash
158159
- the first step copies .tool-versions from /home/vscode to $HOME/.tool-versions
159-
## Using local or pull request images in Visual Studio Code
160+
## Using local or pull request images in Visual Studio Code and GitHub Actions
160161
You can use local or pull request images by changing IMAGE_VERSION in devcontainer.json.
161162
For an image built locally following instructions below, you should put the IMAGE_VERSION=local-build.
162163
For an image built from a pull request, you should put the IMAGE_VERSION=<tag of image as shown in pull request job>.
163164
You can only use images built from a pull request for testing changes in GitHub Actions.
164165

166+
# Common Makefile targets
167+
There is a set of common Makefiles that are defined in `src/base/.devcontainer/Mk` and are included from `common.mk`. These are installed to /usr/local/share/eps/Mk on the base image, so they are available for all containers.
168+
169+
This should be added to the end of each project's Makefile to include them
170+
```
171+
%:
172+
@$(MAKE) -f /usr/local/share/eps/Mk/common.mk $@
173+
```
174+
# Targets
175+
The following targets are defined. These are needed for quality checks to run. Some targets are project-specific and should be overridden in the project's Makefile.
176+
177+
Build targets (`build.mk`)
178+
- `install` - placeholder target - should be overridden locally
179+
- `install-node` - placeholder target - should be overridden locally
180+
- `docker-build` - placeholder target - should be overridden locally
181+
- `compile` - placeholder target - should be overridden locally
182+
183+
Check targets (`check.mk`)
184+
- `lint` - placeholder target - should be overridden locally
185+
- `test` - placeholder target - should be overridden locally
186+
- `shellcheck` - runs shellcheck on `scripts/*.sh` and `.github/scripts/*.sh` when files exist
187+
- `cfn-lint` - runs `cfn-lint` against `cloudformation/**/*.yml|yaml` and `SAMtemplates/**/*.yml|yaml`
188+
- `cdk-synth` - placeholder target - should be overridden locally
189+
- `cfn-guard-sam-templates` - validates SAM templates against cfn-guard rulesets and writes outputs to `.cfn_guard_out/`
190+
- `cfn-guard-cloudformation` - validates `cloudformation` templates against cfn-guard rulesets and writes outputs to `.cfn_guard_out/`
191+
- `cfn-guard-cdk` - validates `cdk.out` against cfn-guard rulesets and writes outputs to `.cfn_guard_out/`
192+
- `cfn-guard-terraform` - validates `terraform_plans` against cfn-guard rulesets and writes outputs to `.cfn_guard_out/`
193+
- `actionlint` - runs actionlint against GitHub Actions
194+
- `secret-scan` - runs git-secrets (including scanning history) against the repository
195+
- `guard-<ENVIRONMENT_VARIABLE>` - checks if an environment variable is set and errors if it is not
196+
197+
Credentials targets (`credentials.mk`)
198+
- `aws-configure` - configures an AWS SSO session
199+
- `aws-login` - Authorizes an SSO session with AWS so AWS CLI tools can be used. You may still need to set AWS_PROFILE before running commands
200+
- `github-login` - Authorizes GitHub CLI to GitHub with scope to read packages
201+
- `create-npmrc` - depends on `github-login`, then writes `.npmrc` with a GitHub Packages auth token and `@nhsdigital` registry
202+
203+
Trivy targets (`trivy.mk`)
204+
- `trivy-license-check` - runs Trivy license scan (HIGH/CRITICAL) and writes `.trivy_out/license_scan.txt`
205+
- `trivy-generate-sbom` - generates CycloneDX SBOM at `.trivy_out/sbom.cdx.json`
206+
- `trivy-scan-python` - scans Python dependencies (HIGH/CRITICAL) and writes `.trivy_out/dependency_results_python.txt`
207+
- `trivy-scan-node` - scans Node dependencies (HIGH/CRITICAL) and writes `.trivy_out/dependency_results_node.txt`
208+
- `trivy-scan-go` - scans Go dependencies (HIGH/CRITICAL) and writes `.trivy_out/dependency_results_go.txt`
209+
- `trivy-scan-java` - scans Java dependencies (HIGH/CRITICAL) and writes `.trivy_out/dependency_results_java.txt`
210+
- `trivy-scan-docker` - scans a built image (HIGH/CRITICAL) and writes `.trivy_out/dependency_results_docker.txt` (requires `DOCKER_IMAGE`), for example:
211+
165212
# Project structure
166213
We have 5 types of dev container. These are defined under src
167214

@@ -303,7 +350,7 @@ CONTAINER_NAME=base \
303350
make shell-image
304351
```
305352

306-
## Generating a .trivyignore file
353+
# Generating a .trivyignore file
307354
You can generate a .trivyignore file for known vulnerabilities by either downloading the JSON scan output generated by the build, or by generating it locally using the scanning images commands above with a make target of scan-image-json
308355

309356
If generated locally, then the output goes into .out/scan_results_docker.json.
@@ -322,7 +369,7 @@ poetry run python \
322369
--output src/projects/fhir_facade_api/.trivyignore.new.yaml
323370
```
324371

325-
## Cleaning up unused container images
372+
# Cleaning up unused container images
326373

327374
There is a script to delete unused container images. This runs on every merge to main and deletes pull request images, and on a weekly schedule it deletes images created by CI.
328375
You can run it manually using the following. Using the `dry-run` flag just shows what would be deleted
@@ -341,49 +388,3 @@ Flags:
341388
- `--delete-ci` deletes images tagged with `ci-<8 hex sha>...` or `githubactions-ci-<8 hex sha>...`.
342389

343390
If neither `--delete-pr` nor `--delete-ci` is set, the script defaults to `--delete-pr`.
344-
345-
## Common Makefile targets
346-
There is a set of common Makefiles that are defined in `src/base/.devcontainer/Mk` and are included from `common.mk`. These are installed to /usr/local/share/eps/Mk on the base image, so they are available for all containers.
347-
348-
This should be added to the end of each project's Makefile to include them
349-
```
350-
%:
351-
@$(MAKE) -f /usr/local/share/eps/Mk/common.mk $@
352-
```
353-
### Targets
354-
The following targets are defined. These are needed for quality checks to run. Some targets are project-specific and should be overridden in the project's Makefile.
355-
356-
Build targets (`build.mk`)
357-
- `install` - placeholder target - should be overridden locally
358-
- `install-node` - placeholder target - should be overridden locally
359-
- `docker-build` - placeholder target - should be overridden locally
360-
- `compile` - placeholder target - should be overridden locally
361-
362-
Check targets (`check.mk`)
363-
- `lint` - placeholder target - should be overridden locally
364-
- `test` - placeholder target - should be overridden locally
365-
- `shellcheck` - runs shellcheck on `scripts/*.sh` and `.github/scripts/*.sh` when files exist
366-
- `cfn-lint` - runs `cfn-lint` against `cloudformation/**/*.yml|yaml` and `SAMtemplates/**/*.yml|yaml`
367-
- `cdk-synth` - placeholder target - should be overridden locally
368-
- `cfn-guard-sam-templates` - validates SAM templates against cfn-guard rulesets and writes outputs to `.cfn_guard_out/`
369-
- `cfn-guard-cloudformation` - validates `cloudformation` templates against cfn-guard rulesets and writes outputs to `.cfn_guard_out/`
370-
- `cfn-guard-cdk` - validates `cdk.out` against cfn-guard rulesets and writes outputs to `.cfn_guard_out/`
371-
- `cfn-guard-terraform` - validates `terraform_plans` against cfn-guard rulesets and writes outputs to `.cfn_guard_out/`
372-
- `actionlint` - runs actionlint against GitHub Actions
373-
- `secret-scan` - runs git-secrets (including scanning history) against the repository
374-
- `guard-<ENVIRONMENT_VARIABLE>` - checks if an environment variable is set and errors if it is not
375-
376-
Credentials targets (`credentials.mk`)
377-
- `aws-configure` - configures an AWS SSO session
378-
- `aws-login` - Authorizes an SSO session with AWS so AWS CLI tools can be used. You may still need to set AWS_PROFILE before running commands
379-
- `github-login` - Authorizes GitHub CLI to GitHub with scope to read packages
380-
- `create-npmrc` - depends on `github-login`, then writes `.npmrc` with a GitHub Packages auth token and `@nhsdigital` registry
381-
382-
Trivy targets (`trivy.mk`)
383-
- `trivy-license-check` - runs Trivy license scan (HIGH/CRITICAL) and writes `.trivy_out/license_scan.txt`
384-
- `trivy-generate-sbom` - generates CycloneDX SBOM at `.trivy_out/sbom.cdx.json`
385-
- `trivy-scan-python` - scans Python dependencies (HIGH/CRITICAL) and writes `.trivy_out/dependency_results_python.txt`
386-
- `trivy-scan-node` - scans Node dependencies (HIGH/CRITICAL) and writes `.trivy_out/dependency_results_node.txt`
387-
- `trivy-scan-go` - scans Go dependencies (HIGH/CRITICAL) and writes `.trivy_out/dependency_results_go.txt`
388-
- `trivy-scan-java` - scans Java dependencies (HIGH/CRITICAL) and writes `.trivy_out/dependency_results_java.txt`
389-
- `trivy-scan-docker` - scans a built image (HIGH/CRITICAL) and writes `.trivy_out/dependency_results_docker.txt` (requires `DOCKER_IMAGE`), for example:

0 commit comments

Comments
 (0)