diff --git a/.github/workflows/mega-linter.yml b/.github/workflows/mega-linter.yml index 600e924..54f7866 100644 --- a/.github/workflows/mega-linter.yml +++ b/.github/workflows/mega-linter.yml @@ -40,6 +40,9 @@ env: # Set to simple to avoid external images in generated markdown REPORTERS_MARKDOWN_TYPE: simple + # Run MegaLinter in parallel to speed up the process. GH hosted runners have 4 CPU cores. + PARALLEL_PROCESS_NUMBER: 4 + concurrency: group: "${{ github.head_ref || github.ref }}-${{ github.workflow }}" cancel-in-progress: true diff --git a/.mega-linter.yml b/.mega-linter.yml index 9aee88c..5ca03d6 100644 --- a/.mega-linter.yml +++ b/.mega-linter.yml @@ -24,6 +24,7 @@ DISABLE: - SPELL DISABLE_LINTERS: + - REPOSITORY_GITLEAKS # Superseded by REPOSITORY_BETTERLEAKS - REPOSITORY_DEVSKIM - REPOSITORY_TRUFFLEHOG - REPOSITORY_GIT_DIFF @@ -42,3 +43,7 @@ YAML_V8R_FILTER_REGEX_EXCLUDE: "dependabot.yml" # Dependabot yaml in SchemaStore # This whitelists GITHUB_TOKEN so zizmor can authenticate with the GitHub API to resolve the uses: clauses in our workflow files. ACTION_ZIZMOR_UNSECURED_ENV_VARIABLES: - GITHUB_TOKEN + +REPOSITORY_KINGFISHER_ARGUMENTS: + - --exclude + - "**/.venv/**" diff --git a/Makefile b/Makefile index b69f9bd..1177efa 100644 --- a/Makefile +++ b/Makefile @@ -38,11 +38,12 @@ install-dev: ## Install the dependencies including dev. poetry install .PHONY: megalint -megalint: ## Run the mega-linter. +megalint: ## Run the mega-linter. Use LINTER=NAME to run only one. docker run --platform linux/amd64 --rm \ -v /var/run/docker.sock:/var/run/docker.sock:rw \ -v $(shell pwd):/tmp/lint:rw \ - oxsecurity/megalinter:v9 + $(if $(LINTER),-e ENABLE_LINTERS=$(LINTER),) \ + ghcr.io/oxsecurity/megalinter:v9 .PHONY: update-template-packages update-template-packages: ## Refresh package-manager template files and lockfiles. diff --git a/README.md b/README.md index e382e66..208158d 100644 --- a/README.md +++ b/README.md @@ -429,21 +429,34 @@ There are many alternatives to the tools used in this template, and you may pref - Integrate with the ONS Software Developer Portal. - Ability to update the project with the latest template changes. +--- + ## Development -:TODO: Add instructions for development +Get started with development by running the following commands. +A Makefile is provided to simplify common development tasks. To view all available commands, run: -### Maintainer Commands +```bash +make +``` -Use `make update-template-packages` when you need to refresh the package-manager-specific template files under -`project_template/` after changing the dependency sets or package-manager template configuration. +### Installation -This command regenerates the managed package files for Poetry, Pipenv, and uv, including the lockfiles copied into the -template. It requires the relevant package-manager CLIs to be installed locally: `poetry`, `pipenv`, and `uv`. +Install all dependencies including dev: + +```bash +make install-dev +``` + +Install only production dependencies: + +```bash +make install +``` -### Pre-commit hooks +### Pre-commit Hooks -This repository includes a `.pre-commit-config.yaml` for lightweight repository checks and Python linting with Ruff. +This repository includes a `.pre-commit-config.yaml` for repository hygiene checks and Python linting with Ruff. Install the hooks locally with: @@ -457,6 +470,72 @@ Run the full hook set on demand with: make pre-commit ``` +### Run Tests + +The unit tests are written using the [pytest](https://docs.pytest.org/en/stable/) framework. To run the tests, run: + +```bash +make test +``` + +### Linting and Formatting + +Various tools are used to lint and format the code in this project. + +#### Python + +The project uses [Ruff](https://github.com/astral-sh/ruff) and [pylint](https://pylint.pycqa.org/en/latest/index.html) +for linting and formatting of the Python code. The tools are configured using `pyproject.toml`. + +To lint the Python code, run: + +```bash +make lint +``` + +To auto-format the Python code and fix linting issues, run: + +```bash +make format +``` + +#### MegaLinter (non-Python files) + +[MegaLinter](https://github.com/oxsecurity/megalinter) is used to lint non-Python files in the project (YAML, GitHub +Actions, Shell scripts, etc.). It is configured using `.mega-linter.yml`. + +To run MegaLinter, ensure you have **Docker** installed on your system. + +> [!NOTE] +> +> 1. If you use Colima for Docker on macOS, run `colima start --edit` and set `mountType: virtiofs` in the profile YAML +> so that bind mounts work correctly with `make megalint`. +> 2. The initial run may take some time while the Docker image is downloaded. +> Subsequent runs will be considerably faster due to Docker caching. 🚀 + +To start the linter and automatically fix fixable issues, run: + +```bash +make megalint +``` + +To run only a specific linter, pass the `LINTER` variable: + +```bash +make megalint LINTER=YAML_YAMLLINT +``` + +This maps to MegaLinter's `ENABLE_LINTERS` environment variable. See the +[supported linters list](https://megalinter.io/latest/supported-linters/) for valid names. + +### Maintainer Commands + +Use `make update-template-packages` when you need to refresh the package-manager-specific template files under +`project_template/` after changing the dependency sets or package-manager template configuration. + +This command regenerates the managed package files for Poetry, Pipenv, and uv, including the lockfiles copied into the +template. It requires the relevant package-manager CLIs to be installed locally: `poetry`, `pipenv`, and `uv`. + ## Contributing See [CONTRIBUTING.md](CONTRIBUTING.md) for details. diff --git a/project_template/.github/workflows/ci.yml.jinja b/project_template/.github/workflows/ci.yml.jinja index 235dfc4..a45bc8f 100644 --- a/project_template/.github/workflows/ci.yml.jinja +++ b/project_template/.github/workflows/ci.yml.jinja @@ -1,5 +1,8 @@ --- name: CI +permissions: + contents: read + pull-requests: write on: # yamllint disable-line rule:truthy push: diff --git a/project_template/.github/workflows/mega-linter.yml b/project_template/.github/workflows/mega-linter.yml index 3a1e131..54f7866 100644 --- a/project_template/.github/workflows/mega-linter.yml +++ b/project_template/.github/workflows/mega-linter.yml @@ -40,6 +40,9 @@ env: # Set to simple to avoid external images in generated markdown REPORTERS_MARKDOWN_TYPE: simple + # Run MegaLinter in parallel to speed up the process. GH hosted runners have 4 CPU cores. + PARALLEL_PROCESS_NUMBER: 4 + concurrency: group: "${{ github.head_ref || github.ref }}-${{ github.workflow }}" cancel-in-progress: true @@ -152,9 +155,12 @@ jobs: github.event.pull_request.head.repo.full_name == github.repository ) && !contains(github.event.head_commit.message, 'skip fix') + env: + PR_NUMBER: ${{ steps.cpr.outputs.pull-request-number }} + PR_URL: ${{ steps.cpr.outputs.pull-request-url }} run: | - echo "PR Number - ${{ steps.cpr.outputs.pull-request-number }}" - echo "PR URL - ${{ steps.cpr.outputs.pull-request-url }}" + echo "PR Number - $PR_NUMBER" + echo "PR URL - $PR_URL" # Push new commit if applicable # (for now works only on PR from same repository, not from forks) diff --git a/project_template/.mega-linter.yml b/project_template/.mega-linter.yml index 9aee88c..62f4864 100644 --- a/project_template/.mega-linter.yml +++ b/project_template/.mega-linter.yml @@ -24,6 +24,7 @@ DISABLE: - SPELL DISABLE_LINTERS: + - REPOSITORY_GITLEAKS # Superseded by REPOSITORY_BETTERLEAKS - REPOSITORY_DEVSKIM - REPOSITORY_TRUFFLEHOG - REPOSITORY_GIT_DIFF diff --git a/project_template/.prettierignore b/project_template/.prettierignore new file mode 100644 index 0000000..d2bafae --- /dev/null +++ b/project_template/.prettierignore @@ -0,0 +1 @@ +.copier-answers.yml diff --git a/project_template/Makefile.jinja b/project_template/Makefile.jinja index df44558..09d7b0a 100644 --- a/project_template/Makefile.jinja +++ b/project_template/Makefile.jinja @@ -67,11 +67,12 @@ install-dev: ## Install the dependencies including dev. {%- endif %} .PHONY: megalint -megalint: ## Run the mega-linter. +megalint: ## Run the mega-linter. Use LINTER=NAME to run only one. docker run --platform linux/amd64 --rm \ -v /var/run/docker.sock:/var/run/docker.sock:rw \ -v $(shell pwd):/tmp/lint:rw \ - oxsecurity/megalinter:v9 + $(if $(LINTER),-e ENABLE_LINTERS=$(LINTER),) \ + ghcr.io/oxsecurity/megalinter:v9 {% if enable_copier_updates %} .PHONY: copier-update copier-update: ## Update the project using the initial copier template. diff --git a/project_template/README.md.jinja b/project_template/README.md.jinja index c7cd317..5a964a5 100644 --- a/project_template/README.md.jinja +++ b/project_template/README.md.jinja @@ -158,8 +158,12 @@ configured using the `.mega-linter.yml` file. To run MegaLinter, ensure you have **Docker** installed on your system. -> Note: The initial run may take some time to download the Docker image. However, subsequent executions will be -> considerably faster due to Docker caching. :rocket: +> [!NOTE] +> +> 1. If you use Colima for Docker on macOS, run `colima start --edit` and set `mountType: virtiofs` in the profile YAML +> so that bind mounts work correctly with `make megalint`. +> 2. The initial run may take some time while the Docker image is downloaded. +> Subsequent runs will be considerably faster due to Docker caching. 🚀 To start the linter and automatically rectify fixable issues, run: @@ -167,6 +171,15 @@ To start the linter and automatically rectify fixable issues, run: make megalint ``` +To run only a specific linter, pass `LINTER` variable: + +```bash +make megalint LINTER=YAML_YAMLLINT +``` + +This maps to MegaLinter's `ENABLE_LINTERS` environment variable. See the +[supported linters list](https://megalinter.io/latest/supported-linters/) for valid names. + ## Contributing See [CONTRIBUTING.md](CONTRIBUTING.md) for details.