GitHub Policy Audit

A tool used to audit GitHub Organisations for compliance with ONS' GitHub Usage Policy. Built using the KEH Policy Methods Library, this tool produces a report of the audit findings, which can be used to identify areas of non-compliance and inform remediation efforts. Additionally, these reports can track compliance over time, providing a historical record of the organisation's adherence to the policy, and its progress towards achieving compliance.

Table of Contents

• GitHub Policy Audit
  • Table of Contents
  • Prerequisites
  • Makefile
  • Running the Project
  • Deployment
    • Deployments with Concourse
    • Manual Deployment
  • Documentation
    • GitHub Actions for Documentation
    • Local Development of Documentation
  • Linting and Testing
    • GitHub Actions
    • Running Tests and Linters Locally
      • Primary Language
      • MegaLinter
      • Documentation linting and building

Prerequisites

• Python 3.12 or higher
• Poetry for dependency management
• Node.js and npm for documentation linting (Markdownlint)

Makefile

This project uses a Makefile to simplify common tasks. To see the available commands, run:

make help

Running the Project

Deployment

Deployments with Concourse

Manual Deployment

Documentation

This repository uses MkDocs for documentation. The documentation source files are located in the docs directory.

GitHub Actions for Documentation

MkDocs gets deployed to GitHub Pages using GitHub Actions. The workflow for this is located at .github/workflows/deploy-docs.yml. Before deployment, another GitHub Action workflow runs to check that the documentation builds correctly and has no linting or formatting issues. This workflow is located at .github/workflows/ci-docs.yml.

Local Development of Documentation

To run the documentation locally:

1. Create a Python virtual environment and activate it.

   python -m venv venv
   source venv/bin/activate

2. Install the dependencies for MkDocs.

   make docs-install

3. Run the MkDocs development server.

   make docs-serve

Linting and Testing

GitHub Actions

This repository has GitHub Actions workflows set up for linting and testing. The workflows are located at:

• .github/workflows/ci-fmt.yml for linting and formatting checks (primary language).
• .github/workflows/ci-test.yml for running automated tests.
• .github/workflows/ci-docs.yml for checking that the documentation builds correctly and has no linting or formatting issues.
• .github/workflows/megalinter.yml for running MegaLinter, which checks for linting and formatting issues across multiple languages and file types (this is a catch-all linter).
• .github/workflows/deploy-docs.yml for deploying documentation to GitHub Pages.

Running Tests and Linters Locally

Primary Language

To run the linters and formatters for the primary language (Python) locally, you can use the following command:

make lint

To apply automatic fixes for any linting or formatting issues found, you can use:

make fmt

To run the tests locally, you can use:

make test-unit

MegaLinter

This repository uses MegaLinter for comprehensive linting across multiple languages and file types. We use this so that all additional assets in the repository (e.g. YAML files, Markdown files, etc.) are also linted and checked for formatting issues, without having to set up specific linters for each file type.

To run MegaLinter locally, you can use the following command:

make megalinter

Documentation linting and building

This repository uses Markdownlint for linting the documentation. To run Markdownlint locally, you can use the following:

make docs-lint

Note: This will install markdownlint-cli globally via npm if it is not already installed.

To apply automatic fixes for any linting issues found by Markdownlint, you can use:

make docs-fix

To test that the documentation builds correctly, you can use the following command:

make docs-build

Note: This depends on MkDocs being set up for the repository. Instructions for setting up MkDocs can be found in the Documentation section of this README.