ELI-338: Adds readme for deployment (#317)

shweta-nhs · web-flow · commit ca70f0e10ea1 · 2026-01-22T16:37:40.000Z
* ELI-338: Adds readme for deployment

* ELI-338: Fixes 'English' and 'Markdown'

* ELI-338: Adds proxygen and apim to vale accept list

* ELI-338: Fixing vale

* ELI-338: Fixing vale

* ELI-338: Fixing vale
diff --git a/.github/DEPLOYMENT_README.md b/.github/DEPLOYMENT_README.md
@@ -0,0 +1,73 @@
+# GitHub Workflows for eligibility-signposting-api-specification
+
+This directory contains GitHub Actions workflows that automate CI/CD processes for the eligibility-signposting-api-specification project. These workflows manage deployment, tagging, and notifications for different environments (dev, sandbox, preprod, prod) and integrate with external tools like proxygen and Postman.
+
+## Workflows Overview
+
+### 1. dev_sandbox_publish_deploy.yaml
+
+- **Triggers:** On push to `main` branch.
+- **Environments:** dev, sandbox.
+- **Steps:**
+  - Sets a version tag based on the current timestamp.
+  - Installs dependencies (Python, Node.js, Poetry, proxygen-cli).
+  - Generates and publishes OpenAPI specs to proxygen for dev and sandbox.
+  - Publishes the Postman collection to Postman.
+  - Tags the deployment in Git (Example tag: spec-20260122155331).
+  - Notifies a Slack channel on completion.
+
+### 2. preprod_publish_deploy.yaml
+
+- **Triggers:** Manually via GitHub UI (`workflow_dispatch`).
+- **Inputs:** Tag to promote (defaults to latest).
+- **Environment:** preprod.
+- **Steps:**
+  - Checks out the specified tag.
+  - Installs dependencies.
+  - Generates and publishes the OpenAPI spec to proxygen for preprod.
+  - Deploys the spec to the preprod proxygen instance.
+
+### 3. prod_publish_deploy.yaml
+
+- **Triggers:** Manually via GitHub UI (`workflow_dispatch`).
+- **Inputs:** Tag to promote (required).
+- **Environment:** Prod.
+- **Steps:**
+  - Checks out the specified tag.
+  - Installs dependencies.
+  - Generates and publishes the OpenAPI spec to proxygen for Prod.
+  - Deploys the spec to the Prod proxygen instance.
+  - Creates a GitHub Release for the deployed tag.
+
+## How to Use
+
+### dev & sandbox deployment
+
+- Push changes to the `main` branch.
+- The workflow will automatically:
+  - Deploy to dev and sandbox.
+  - Publish the Postman collection.
+  - Tag the deployment.
+  - Notify Slack.
+
+### preprod deployment
+
+- Go to the **Actions** tab in GitHub.
+- Select **Deploy to preprod** workflow.
+- Click **Run workflow**.
+- Enter the tag to promote (or use the default `latest`).
+- The workflow will deploy the specified tag to preprod.
+
+### prod deployment
+
+- Go to the **Actions** tab in GitHub.
+- Select **Deploy to Prod** workflow.
+- Click **Run workflow**.
+- Enter the tag to promote (must match a tag from previous deployments).
+- The workflow will deploy the specified tag to Prod and create a GitHub Release.
+
+## Notes
+
+- All workflows require secrets to be set in the repository (e.g., `PROXYGEN_PRIVATE_KEY`, `POSTMAN_API_KEY`, `SLACK_WORKFLOW_WEBHOOK_URL`, `GITHUB_TOKEN`).
+- The tags created follow the format `spec-YYYYMMDDHHMMSS` indicative of the deployment time. This is NOT related to the [specification/eligibility-signposting-api](../specification/eligibility-signposting-api.yaml) version.
+- For more details, see the steps in each workflow YAML file.
diff --git a/README.md b/README.md
@@ -1,46 +1,24 @@
-# Repository Template
+# Eligibility Signposting Specification
 
-[![CI/CD Pull Request](https://github.com/nhs-england-tools/repository-template/actions/workflows/cicd-1-pull-request.yaml/badge.svg)](https://github.com/nhs-england-tools/repository-template/actions/workflows/cicd-1-pull-request.yaml)
-[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=repository-template&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=repository-template)
-
-Start with an overview or a brief description of what the project is about and what it does. For example -
-
-Welcome to our repository template designed to streamline your project setup! This robust template provides a reliable starting point for your new projects, covering an essential tech stack and encouraging best practices in documenting.
-
-This repository template aims to foster a user-friendly development environment by ensuring that every included file is concise and adequately self-documented. By adhering to this standard, we can promote increased clarity and maintainability throughout your project's lifecycle. Bundled within this template are resources that pave the way for seamless repository creation. Currently supported technologies are:
-
-- Docker
-
-Make use of this repository template to expedite your project setup and enhance your productivity right from the get-go. Enjoy the advantage of having a well-structured, self-documented project that reduces overhead and increases focus on what truly matters - coding!
+This repository contains the OpenAPI specification and related tooling for the Eligibility Signposting API.
 
 ## Table of Contents
 
-- [Repository Template](#repository-template)
+- [Repository Template](#eligibility-signposting-specification)
   - [Table of Contents](#table-of-contents)
-  - [Setup](#setup)
+  - [Information](#information)
     - [Prerequisites](#prerequisites)
     - [Configuration](#configuration)
-  - [Usage](#usage)
-    - [Testing](#testing)
   - [Sandbox](#sandbox)
   - [Specification](#specification)
-  - [Design](#design)
-    - [Diagrams](#diagrams)
-    - [Modularity](#modularity)
+  - [Deployment](#deployment)
   - [Contributing](#contributing)
   - [Contacts](#contacts)
   - [Licence](#licence)
 
-## Setup
+## Information
 
-By including preferably a one-liner or if necessary a set of clear CLI instructions we improve user experience. This should be a frictionless installation process that works on various operating systems (macOS, Linux, Windows WSL) and handles all the dependencies.
-
-Clone the repository
-
-```shell
-git clone https://github.com/nhs-england-tools/repository-template.git
-cd nhs-england-tools/repository-template
-```
+This repository was cloned from the [nhs-england-tools/repository-template](https://github.com/nhs-england-tools/repository-template.git)
 
 ### Prerequisites
 
@@ -78,46 +56,18 @@ Installation and configuration of the toolchain dependencies
 make config
 ```
 
-## Usage
-
-After a successful installation, provide an informative example of how this project can be used. Additional code snippets, screenshots and demos work well in this space. You may also link to the other documentation resources, e.g. the [User Guide](./docs/user-guide.md) to demonstrate more use cases and to show more features.
-
-### Testing
-
-There are `make` tasks for you to configure to run your tests.  Run `make test` to see how they work.  You should be able to use the same entry points for local development as in your CI pipeline.
-
 ## Sandbox
 
-There is a minimalist sandbox environment in `/sandbox` with an accompanying README with instructions on how to run it locally.
+There is a minimalist sandbox environment in `sandbox` with an accompanying [README](sandbox/README.md) with instructions on how to run it locally.
 
 ## Specification
 
-The OpenAPI specification is stored in `specification`. In that folder, there is an accompanying README with instructions on how to produce an environment-specification specification and publish
-it using Proxygen CLI.
-
-## Design
-
-### Diagrams
-
-The [C4 model](https://c4model.com/) is a simple and intuitive way to create software architecture diagrams that are clear, consistent, scalable and most importantly collaborative. This should result in documenting all the system interfaces, external dependencies and integration points.
-
-![Repository Template](./docs/diagrams/Repository_Template_GitHub_Generic.png)
-
-The source for diagrams should be in Git for change control and review purposes. Recommendations are [draw.io](https://app.diagrams.net/) (example above in [docs](.docs/diagrams/) folder) and [Mermaids](https://github.com/mermaid-js/mermaid). Here is an example Mermaids sequence diagram:
-
-```mermaid
-sequenceDiagram
-    User->>+Service: GET /users?params=...
-    Service->>Service: auth request
-    Service->>Database: get all users
-    Database-->>Service: list of users
-    Service->>Service: filter users
-    Service-->>-User: list[User]
-```
+The OpenAPI specification is stored in `specification`. In that folder, there is an accompanying [README](specification/README.md) with instructions on how to produce an environment-specific specification and publish
+it using proxygen CLI.
 
-### Modularity
+## Deployment
 
-Most of the projects are built with customisability and extendability in mind. At a minimum, this can be achieved by implementing service level configuration options and settings. The intention of this section is to show how this can be used. If the system processes data, you could mention here for example how the input is prepared for testing - anonymised, synthetic or live data.
+The deployment workflows are defined in the `.github/workflows/` folder. There is an accompanying [README](.github/DEPLOYMENT_README.md) with details on how the deployment works and how to use it.
 
 ## Contributing
 
diff --git a/scripts/config/vale/styles/config/vocabularies/words/accept.txt b/scripts/config/vale/styles/config/vocabularies/words/accept.txt
@@ -25,3 +25,5 @@ Terraform
 toolchain
 Trufflehog
 uat
+proxygen
+APIM
