ministryofjustice / tech-docs-github-pages-publisher

Docker image to publish MoJ documentation repositories as github pages sites • This repository is defined and managed in Terraform

Tech Docs GitHub Pages Publisher

This repository publishes a utility container for previewing and packaging GOV.UK's Technical Documentation Template.

⚠️ Breaking Changes

v4

The scripts have moved:

• /scripts/deploy.sh is now /usr/local/bin/package

• /scripts/preview.sh is now /usr/local/bin/preview

v3

The scripts in the Docker container have changed.

scripts/deploy.sh is now used to check internal links only during deployment. See .github/workflows/publish-gh-pages.yml below.

If you see an error like this:

  internally linking to ./*-communications-plan.html#tips-on-format-of-communications-examples; the file exists, but the hash 'tips-on-format-of-communications-examples' does not

You can override the check_interal_hash argument with scripts/deploy.sh false

[Optional]: Use the scripts/check-url-links.sh to test internal and external URLs. It may produce false errors for valid working URLs. Add the .github/workflows/check-links.yml below to run the check when the PR is created. The false errors can be ignored.

[Optional]: Use the url-check job within .github/workflows/publish-gh-pages.yml to check the URLs are correct post-deployment. Private and internal Github repository URLs and other URLs that create false errors can be listed and skipped within this job.

v2

If you have a branch called gh-pages already rename it to gh-pages-old. In repository settings, go to Pages, copy the 'Custom domain' value, and for 'Build and deployment' 'Source' change to the option 'GitHubs Actions'. Apply the yml code below to your CI Actions. If all is working you can remove the gh-pages-old branch. You may need to manually run the below workflow once it is merged into the main.

Usage

GitHub Actions

Examples of how to use the container can be found below:

• build-test.yml

• publish.yml

Locally

To preview locally, you will need Docker, and then you can run the following:

docker run -it --rm \
  --name tech-docs-github-pages-publisher \
  --publish 4567:4567 \
  --volume $(pwd)/config:/app/config \
  --volume $(pwd)/source:/app/source \
  ministryofjustice/tech-docs-github-pages-publisher:v4.0.0 /usr/local/bin/preview

Update Dependencies

Dependabot should take care of updating dependencies in Gemfile and Gemfile.lock.

However, if you need to update manually, you can do the following:

1. Build the image

   docker build --file Dockerfile --tag ministryofjustice/tech-docs-github-pages-publisher:local .

2. Extract Gemfile.lock

   docker run -it --rm ministryofjustice/tech-docs-github-pages-publisher:local
   
   cat /opt/publisher/Gemfile.lock

3. Replace Gemfile.lock

Release

To create a new release:

1. Push to the main branch.

2. Create a new tag using git tag vn.n.n where n.n.n is the version number. Please follow semantic versioning.

3. Push the tag to the remote repository using git push origin --tags.

4. The "release" CICD pipeline is triggered, creating the release and performing the relevant docker actions.

To create a new release, follow GitHub's procedure

tech-docs-github-pages-publisher's Issues

A branch protection setting is not enabled: codeowners require reviews

Hi there
The default branch protection setting called codeowners require review is not enabled for this repository
This option affects a pull request, i.e a PR will need to be reviewed and approved by a CODEOWNER before it can be merged.
See repository settings/Branches/Branch protection rules
Either add a new Branch protection rule or edit the existing branch protection rule and select the Require review from Code Owners option
Create a .github/CODEOWNERS file
Add a or multiple entries of @ministryofjustice/team_name to the CODEOWNERS file
The team_name shall be a team from within the MoJ teams: https://github.com/orgs/ministryofjustice/teams
See GH Codeowners documentation: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
See the repository standards: https://github.com/ministryofjustice/github-repository-standards
See the report: https://operations-engineering-reports.cloud-platform.service.justice.gov.uk/github_repositories
Please contact Operations Engineering on Slack #ask-operations-engineering, if you need any assistance

A branch protection setting is not enabled: requires approving reviews

Hi there
The default branch protection setting called requires approving reviews is not enabled for this repository
See repository settings/Branches/Branch protection rules
Either add a new Branch protection rule or edit the existing branch protection rule and select the Require approvals option
This will require another persons approval on a pull request before it can be merged
See the repository standards: https://github.com/ministryofjustice/github-repository-standards
See the report: https://operations-engineering-reports.cloud-platform.service.justice.gov.uk/github_repositories
Please contact Operations Engineering on Slack #ask-operations-engineering, if you need any assistance

User access removed, access is now via a team

Hi there

The user benmillar-cgi either had direct member access to the repository or had direct member access and access via a team.

Access is now only via a team.

If the user was already in a team, then their direct access to the repository has been removed.

If the user was not in a team, then the user will have been added to an automated generated team named repository-name-<read|write|maintain|admin>-team and their direct access to the repository has been removed.

The list of Org teams can be found at https://github.com/orgs/ministryofjustice/teams or https://github.com/orgs/moj-analytical-services/teams.

The user will have the same level of access to the repository via the team.

The first user added to a team is made a team maintainer, this enables that user to manage the users within the team.

Users with admin access are added to the admin team as a team maintainer.

If you have any questions, please contact us in #ask-operations-engineering on Slack.

This issue can be closed.

Activate relative assets changed in v4.0.0

Hello,

As part of the recent refactor, the following line was removed from the config.rb

activate :relative_assets

New config.rb without the above declaration.

We believe this has caused issues with our tech docs site where before asset URLs were like this:
<link href="stylesheets/manifest.css" rel="stylesheet" />

And now with v4.0.0 are:
<link href="/stylesheets/manifest.css" rel="stylesheet" />

Our GitHub Pages are published to a path in ministryofjustice.github.io, they are not served from a custom domain.

Is there a way to get back or configure the old behaviour? I'm not 100% certain this is the reason as obviously v4.0.0 introduces other changes and bump to different dependencies but we believe this may be likely the cause.

Thank you.

A branch protection setting is not enabled: Include administrators

Hi there
The default branch protection setting called Include administrators is not enabled for this repository
See repository settings/Branches/Branch protection rules
Either add a new Branch protection rule or edit the existing branch protection rule and select the Include administrators option
This will enable the branch protection rules to admin uses as well
See the repository standards: https://github.com/ministryofjustice/github-repository-standards
See the report: https://operations-engineering-reports.cloud-platform.service.justice.gov.uk/github_repositories
Please contact Operations Engineering on Slack #ask-operations-engineering, if you need any assistance