Home Office Forms Guide

This is a GovUK styled wiki built using React and Gatsby to quickly build and setup a static website using Github Actions & Pages for a streamlined way of committing and accessing documentation for a development team.

• HOF Guide site - https://ukhomeofficeforms.github.io/hof-guide/

A new project can use this to setup their own wiki using this repo within 6 easy steps (see 'Repo Setup' below).

GovUK styles and JS taken from static assets generated by the X-GovUK Eleventy Plugin

🚀 Quick start

Repo Setup

1. Fork/clone this repo and stick it into the relevant repo space for your project on Github.

2. Add a repository secret called 'DOCS_ACCESS_TOKEN' which has basic read/write access to the repo. If you are unsure on how to set this up, then refer to Github's docs on How To Setup a Personal Access Token. Once setup, go to your repo's 'Settings' and add the secret under the left hand side Settings navigation bar under 'Security -> Secrets -> Actions'.

   Security Actions Settings

   

   Repository Secret Example

   

3. Add a remote branch for your repo to be used for Github Pages. The default standard for this branch name is 'gh-pages' although you can name it anything you want it to be. Run the following commands locally to set it up:

   git checkout -b gh-pages
   git push origin gh-pages:gh-pages

4. Go to 'Code and automation -> Pages' under the repo's 'Settings', you should get a confirmation of the site address your static site will be deployed to. You can change which branch you want your site to build off if not 'gh-pages'

   Github Pages Settings

   

   Default Configuration Setup for Github Pages

   

5. In the config.js file, update the pathPrefix key to match the repo-name you are pushing this wiki to. In this case, this repo is called hof-guide so you can see this as:

   pathPrefix: '/hof-guide'

   It is also recommended to update the rest of the keys in config.js so that certain site data reflects the documentation for your service. N.B. - Your site will not function properly unless pathPrefix is set to the repo name exactly. It is very important otherwise React's routing will fight with the uri setup by Github Pages

6. Lastly, make your first push to master branch and this should trigger a build process. You can follow this under 'Actions' in the top navigation bar of the repo. Within a few minutes your static site should be available. That's it! You are all setup!

   Github Actions

   

Local Development

1. Installing the Wiki

   Start this site by ensuring at least Node 16.15.0 is installed. You can do this using Node Version Manager (NVM) and following the following instructions:

   # Use Node Version Manager to install Node v16.15.0 (latest LTS version)
   nvm install 18
   # Then use Node v16.15.0 before installing project dependencies
   nvm use 18
   # If yarn is not installed run the following to globally install it
   npm i yarn -g
   # Install project dependencies
   yarn

2. Run the Service

   Run the following to start up the service on Localhost

   yarn run develop

   Any updates will either automatically update the page or require a manual page reload.

Deploying

1. Automated

   Push or merge changes to master branch. These will trigger Git Actions that update and auto-deploy to a gh-pages branch. This in turn will deploy the static site to the relevant Github page link.

2. Manual

   Alternatively you can run the following which is the manual approach to step 1 above.

   yarn run deploy

Troubleshooting

Startup Issues

There have been instances when upon a fresh local installation, the following error appears when running yarn run develop:

error Command failed with signal "SIGSEGV".
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command

It is unknown why this happens currently. However re-running yarn run develop usually makes the error go away.

AVG Web Shield Issues

It appears some Macs running AVG Web Shield receive an Anti-Phishing error when trying to access the deployed Github Page online. It appears Webpack Bundles sometimes trigger this meaning it blocks both this js file and any json/image resources from being cached. Historically this has happened to quite a few other Github Page static sites too. To workaround this you have two options:

OPTION 1 - ADDRESS IT AS AN INDIVIDUAL

Upon getting the AVG alert, make the relevant Github Page exempt by selecting the 3 dots icon (...) and selecting to make it exempt (see below). You can also follow AVG's documentation on 'Excluding certain files and sites from scanning'.

OPTION 2 - ADDRESS IT FOR ALL USERS

Flag the url as a false positive with AVG so their anti-phishing feature whitelists your site via their remote API and thus any stakeholders running AVG on their device aren't flapped by this when checking out your docs. The HOF team did this and we can confirm an AVG support team corrected this within a couple of hours. Here is a reply from them for the reader's reference to confirm it can be resolved quickly and that any concerns around security are addressed:

Thank you for reporting this false positive.

We have now cleared its reputation in our database based on the findings and removed the detection.
This change may take up to 24 hours to take full effect.
Please accept our apology for the inconvenience caused.