diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile index 4f6e87b..7a2f5ce 100644 --- a/.devcontainer/Dockerfile +++ b/.devcontainer/Dockerfile @@ -1,17 +1,17 @@ # See here for image contents: https://github.com/devcontainers/images/tree/main/src -ARG VARIANT="3.14-bookworm" -FROM mcr.microsoft.com/vscode/devcontainers/python:${VARIANT} +# Image version 3.3.2, Python 3.14, Debian bookworm. Tag and digest are updated by Dependabot. +FROM mcr.microsoft.com/vscode/devcontainers/python:3.3.2-3.14-bookworm@sha256:94053b777943a4eda40e83d5386f7c5befb72f5bb778878ac527bb9491adcd42 # [Choice] Node.js version: none, lts/*, 16, 14, 12, 10 ARG NODE_VERSION="none" RUN if [ "${NODE_VERSION}" != "none" ]; then su vscode -c "umask 0002 && . /usr/local/share/nvm/nvm.sh && nvm install ${NODE_VERSION} 2>&1"; fi # Just Installation -COPY --from=ghcr.io/casey/just:latest /just /usr/local/bin/ +COPY --from=ghcr.io/casey/just:1.59.0@sha256:014cbe6e6de678864004e2fd8b0405f77ce43b20b225e816feb330f2fb575c01 /just /usr/local/bin/ # uv Installation -COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /usr/local/bin/ +COPY --from=ghcr.io/astral-sh/uv:0.13.7@sha256:96f40d3904aad8d0bd010539001d36c8e2188b981e1334471a90c4a1d93bb490 /uv /uvx /usr/local/bin/ # [Optional] Uncomment this section to install additional OS packages. # RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \ @@ -19,4 +19,3 @@ COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /usr/local/bin/ # [Optional] Uncomment this line to install global node packages. # RUN su vscode -c "source /usr/local/share/nvm/nvm.sh && npm install -g " 2>&1 - diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index b0dbe90..d0c0f9e 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -6,10 +6,7 @@ "dockerfile": "Dockerfile", "context": "..", "args": { - // Update 'VARIANT' to pick a Python version: 3, 3.10, 3.9, 3.8, 3.7, 3.6 - // Append -bullseye or -buster to pin to an OS version. - // Use -bullseye variants on local on arm64/Apple Silicon. - "VARIANT": "3.14-bookworm", + // The Python version is pinned in the Dockerfile's FROM line (tag + digest). // Options "NODE_VERSION": "none" } diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..d3535f0 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,46 @@ +# Dependabot configuration. +# See https://docs.github.com/en/code-security/dependabot/working-with-dependabot/dependabot-options-reference +version: 2 + +updates: + # GitHub Actions used in .github/workflows (updates SHA pins and their version comments) + - package-ecosystem: "github-actions" + directory: "/" + schedule: + interval: "weekly" + cooldown: + default-days: 7 + labels: ["dependencies"] + groups: + github-actions: + patterns: ["*"] + + # Python dependencies in pyproject.toml / uv.lock + - package-ecosystem: "uv" + directory: "/" + schedule: + interval: "weekly" + cooldown: + default-days: 7 + labels: ["dependencies"] + groups: + python-minor-and-patch: + update-types: ["minor", "patch"] + + # Base image in .devcontainer/Dockerfile + - package-ecosystem: "docker" + directory: "/.devcontainer" + schedule: + interval: "weekly" + cooldown: + default-days: 7 + labels: ["dependencies"] + + # Features in .devcontainer/devcontainer.json + - package-ecosystem: "devcontainers" + directory: "/" + schedule: + interval: "weekly" + cooldown: + default-days: 7 + labels: ["dependencies"] diff --git a/.github/workflows/python.yml b/.github/workflows/python.yml index e527eb9..d7be2e8 100644 --- a/.github/workflows/python.yml +++ b/.github/workflows/python.yml @@ -1,4 +1,4 @@ -name: CI Checks +name: Python CI Checks on: push: @@ -6,31 +6,23 @@ on: pull_request: branches: [ main ] -permissions: - contents: read - pull-requests: read +permissions: {} jobs: code-check-and-unit-test: - runs-on: ubuntu-latest + runs-on: ubuntu-slim steps: - - uses: actions/checkout@v7 + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: - fetch-depth: 0 - - name: Setup just - uses: extractions/setup-just@v3 + persist-credentials: false - name: Install uv - uses: astral-sh/setup-uv@v7 + uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3 with: - enable-cache: true - version: ">=0.11,<0.12" - - name: Check gitleaks - uses: gitleaks/gitleaks-action@v3 - env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - GITLEAKS_ENABLE_COMMENTS: false + enable-cache: false + version: ">=0.13,<0.14" - name: Setup environment run: | + uv tool install rust-just just sync - name: Lint run: | diff --git a/.github/workflows/release-drafter.yml b/.github/workflows/release-drafter.yml index 986ac27..efe79db 100644 --- a/.github/workflows/release-drafter.yml +++ b/.github/workflows/release-drafter.yml @@ -12,21 +12,21 @@ permissions: jobs: update-draft: if: github.event_name == 'push' - runs-on: ubuntu-latest + runs-on: ubuntu-slim permissions: contents: write steps: - - uses: release-drafter/release-drafter@v6 + - uses: release-drafter/release-drafter@978bb0b30c5ee8cdd332ced253758157150d43f0 # v7.10.0 env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} autolabel: if: github.event_name == 'pull_request' && github.event.action != 'labeled' && github.event.action != 'unlabeled' - runs-on: ubuntu-latest + runs-on: ubuntu-slim permissions: pull-requests: write steps: - - uses: release-drafter/release-drafter@v6 + - uses: release-drafter/release-drafter@978bb0b30c5ee8cdd332ced253758157150d43f0 # v7.10.0 with: disable-releaser: true env: @@ -40,7 +40,7 @@ jobs: permissions: pull-requests: read steps: - - uses: mheap/github-action-required-labels@v5 + - uses: mheap/github-action-required-labels@23e10fde7e062233401931a0eece796cd9bf3177 # v5.6.0 with: mode: minimum count: 1 diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 8ab3c0b..d22dbe9 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -16,17 +16,19 @@ jobs: permissions: contents: write steps: - - uses: actions/checkout@v7 + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: ref: main + persist-credentials: false - name: Install uv - uses: astral-sh/setup-uv@v7 + uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3 with: - version: ">=0.11,<0.12" + enable-cache: false + version: ">=0.13,<0.14" - name: Refresh draft release id: drafter - uses: release-drafter/release-drafter@v6 + uses: release-drafter/release-drafter@978bb0b30c5ee8cdd332ced253758157150d43f0 # v7.10.0 env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} @@ -36,7 +38,7 @@ jobs: run: uv version "$VERSION" - name: Update CHANGELOG.md - uses: stefanzweifel/changelog-updater-action@v1 + uses: stefanzweifel/changelog-updater-action@a938690fad7edf25368f37e43a1ed1b34303eb36 # v1.12.0 with: latest-version: ${{ steps.drafter.outputs.tag_name }} release-notes: ${{ steps.drafter.outputs.body }} diff --git a/.github/workflows/security.yml b/.github/workflows/security.yml new file mode 100644 index 0000000..fcca192 --- /dev/null +++ b/.github/workflows/security.yml @@ -0,0 +1,38 @@ +name: GitHub Actions Security Analysis + +on: + push: + branches: ["main"] + pull_request: + branches: ["**"] + +permissions: {} + +jobs: + zizmor: + runs-on: ubuntu-slim + permissions: + contents: read # only needed for private or internal repos + actions: read # only needed for private or internal repos + steps: + - name: Checkout repository + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + + - name: Run zizmor + uses: zizmorcore/zizmor-action@45d7276c9ca790aabd705e31ca99c6185c3e76dd # v0.8.1 + with: + advanced-security: false + gitleaks: + runs-on: ubuntu-slim + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + fetch-depth: 0 + - name: Check gitleaks + uses: gitleaks/gitleaks-action@e0c47f4f8be36e29cdc102c57e68cb5cbf0e8d1e # v3.0.0 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + GITLEAKS_ENABLE_COMMENTS: false diff --git a/Brewfile b/Brewfile index 3448ca2..68ab74e 100644 --- a/Brewfile +++ b/Brewfile @@ -1,3 +1,4 @@ brew "gitleaks" brew "just" brew "uv" +brew "zizmor" diff --git a/CLAUDE.md.example b/CLAUDE.md.example index 453d56a..b7c2395 100644 --- a/CLAUDE.md.example +++ b/CLAUDE.md.example @@ -4,10 +4,14 @@ Python project template using `uv` for environment/dependency management and `ju ## Commands +- `just setup` - install Homebrew tools (`Brewfile`) and sync the project - `just sync` - install all dependency groups into `.venv` - `just lint` - type check (ty), lint + autofix (ruff), format (ruff), spell check (codespell) - `just ci-lint` - same checks without modifying files (used to verify, not fix) - `just test` - run pytest with coverage (fails under 98%) +- `just zizmor` - audit GitHub Actions workflows for security issues +- `just git-leaks` - scan staged changes for secrets +- `just set-github-labels` - create/update the release labels on GitHub (`scripts/sync-labels.sh`, needs `gh`) - `uv add ` / `uv add --dev ` - add a runtime / dev dependency (never edit `uv.lock` by hand) - `uv run example` - run the app entry point @@ -19,6 +23,12 @@ Run `just lint` and `just test` before considering a change done. - `src/example/__init__.py` - `main()` entry point, exposed as the `example` script - `tests/` - pytest tests; import the package as `from example. import ...` - `prek.toml` - git hook config (`prek install` to enable) +- `.github/workflows/` - `python.yml` (lint + tests), `security.yml` (zizmor, gitleaks), + `release-drafter.yml` (draft release, PR labels), `release.yml` (manual release) +- `.github/release-drafter.yml` - release label → version bump / release notes section mapping +- `.github/dependabot.yml` - weekly updates for actions, uv, dev container image and features +- `.devcontainer/` - dev container; base image, `just`, and `uv` pinned by tag + digest +- `scripts/` - repo maintenance scripts ## Conventions @@ -26,3 +36,17 @@ Run `just lint` and `just test` before considering a change done. - Docstrings required in `src/` (ruff `D` rules), not in `tests/` - Type hints on public functions; code must pass `ty check` - Renaming the project means updating `[project] name`, the `src//` folder, and `[project.scripts]` together + +## CI, security, and releases + +- Pin GitHub Actions to a full commit SHA with a version comment (`uses: owner/action@ # vX.Y.Z`); + run `just zizmor` after editing workflows +- Give each workflow/job least-privilege `permissions`; set `persist-credentials: false` on checkout + unless the job pushes +- Pin Docker images as `image:tag@sha256:` +- uv is pinned to 0.13.x in four places that must stay in sync: `[tool.uv] required-version` and the + `uv_build` requirement in `pyproject.toml`, `setup-uv` `version` in the workflows, and the uv image in + `.devcontainer/Dockerfile` +- Do not edit `CHANGELOG.md` or bump `[project] version` by hand; the Release workflow does both +- Every PR needs a release label (GitHub PR label, not a title/commit prefix): `breaking`, `feature`, + `enhancement`, `bug`, `fix`, `chore`, `ci`, `dependencies`, `documentation`, `refactor`, or `skip-changelog` diff --git a/README.md b/README.md index e8a649e..d9241f4 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,7 @@ # Python Project Template [![CI](https://github.com/ahcode0919/python-project-template/actions/workflows/python.yml/badge.svg?branch=main)](https://github.com/ahcode0919/python-project-template/actions/workflows/python.yml) +[![Security](https://github.com/ahcode0919/python-project-template/actions/workflows/security.yml/badge.svg?branch=main)](https://github.com/ahcode0919/python-project-template/actions/workflows/security.yml) [![gitleaks](https://img.shields.io/badge/protected%20by-gitleaks-blue)](https://github.com/gitleaks/gitleaks) Baseline Python project template @@ -11,10 +12,10 @@ Project supports local development and VSCode Dev container development ### Local Development Installation -Note: Project uses `uv` and `just` to manage project configuration and commands +Note: Project uses `uv` (0.13.x, enforced by `required-version` in `pyproject.toml`) and `just` to +manage project configuration and commands -* Install dependencies via Homebrew - `brew bundle install` -* Sync project - `just sync` +* Install tools and sync the project - `just setup` (runs `brew bundle install`, then `just sync`) ### VS Code Dev Container @@ -24,16 +25,36 @@ Note: Project uses `uv` and `just` to manage project configuration and commands * Install recommended extensions * Reopen in container using Remote Development Container menu +The base image, `just`, and `uv` are pinned by version and digest in `.devcontainer/Dockerfile` +and updated by Dependabot. To change the Python version, edit the `FROM` line. + ## Project Commands +* `just setup` - install Homebrew tools from the `Brewfile` and sync the project * `just sync` - sync project dependencies (all groups) * `just lint` - type check, lint, format, and spellcheck project files (applies fixes) * `just ci-lint` - run the same checks without modifying files (used in CI) * `just test` - run unit tests * `just prek` - run pre-commit hooks via prek * `just git-leaks` - scan staged changes for secrets with gitleaks +* `just zizmor` - audit GitHub Actions workflows for security issues +* `just set-github-labels` - create or update the release labels on GitHub (requires `gh auth login`) * `uv add {package}` - install a dependency +## CI and Security + +| Workflow | Runs on | Purpose | +| ------------------------------------------------- | ---------------------------- | ---------------------------------------------- | +| `python.yml` | push / PR to `main` | lint and unit tests | +| `security.yml` | push to `main`, all PRs | zizmor workflow audit, gitleaks secret scan | +| `release-drafter.yml` | push to `main`, PRs | update the draft release, label PRs | +| `release.yml` | manual | publish a release | + +* GitHub Actions are pinned to full commit SHAs, with the version in a trailing comment +* Dependabot (`.github/dependabot.yml`) checks weekly for updates to GitHub Actions, Python + dependencies, the dev container image, and dev container features. New releases wait 7 days + before an update is proposed. Dependabot PRs get the `dependencies` label + ## Releases Releases are managed with [Release Drafter](https://github.com/release-drafter/release-drafter), @@ -56,6 +77,7 @@ labels; other repository labels (e.g. `good first issue`, `question`) are ignore has PRs with different labels, the largest bump wins * Release labels are added automatically from the PR's branch name prefix (`feat/`, `fix/`, `chore/`, `ci/`, `docs/`, `refactor/`) and from the files it changes. You can add or change them by hand +* Run `just set-github-labels` once to create the release labels in the GitHub repository * Merging to `main` updates a draft GitHub Release with the next version and notes * To release, run the **Release** workflow from the Actions tab. It bumps the version in `pyproject.toml`/`uv.lock`, updates `CHANGELOG.md`, tags the release, and uploads build artifacts diff --git a/justfile b/justfile index 87b89ff..abc53e9 100644 --- a/justfile +++ b/justfile @@ -12,7 +12,14 @@ lint: uv run codespell prek: uv run prek +set-github-labels: + ./scripts/sync-labels.sh +setup: + brew bundle install + just sync sync: uv sync --all-groups test: uv run pytest +zizmor: + zizmor . --collect all diff --git a/pyproject.toml b/pyproject.toml index c30e2cb..4e90426 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -7,7 +7,7 @@ requires-python = ">=3.14" dependencies = [] [build-system] -requires = ["uv_build>=0.11.32,<0.12.0"] +requires = ["uv_build>=0.13.7,<0.14.0"] build-backend = "uv_build" [dependency-groups] @@ -40,4 +40,4 @@ extend-ignore = ["E501"] # Line too long (handled by formatter) quote-style = "double" [tool.uv] -required-version = ">=0.11,<0.12" +required-version = ">=0.13,<0.14" diff --git a/scripts/sync-labels.sh b/scripts/sync-labels.sh new file mode 100755 index 0000000..8b8da20 --- /dev/null +++ b/scripts/sync-labels.sh @@ -0,0 +1,29 @@ +#!/usr/bin/env bash +# Create or update the release labels used by Release Drafter. +# Usage: scripts/sync-labels.sh [owner/repo] (defaults to the current repo) +set -euo pipefail + +if [[ $# -gt 0 ]]; then + export GH_REPO="$1" +fi + +# name|color|description +labels=( + "breaking|b60205|Breaking change (major version bump)" + "feature|0e8a16|New feature (minor version bump)" + "enhancement|a2eeef|Improvement to an existing feature (minor version bump)" + "bug|d73a4a|Bug fix (patch version bump)" + "fix|d73a4a|Fix (patch version bump)" + "chore|ededed|Maintenance (patch version bump)" + "ci|1d76db|CI / build tooling (patch version bump)" + "dependencies|0366d6|Dependency update (patch version bump)" + "documentation|0075ca|Documentation (patch version bump)" + "refactor|fbca04|Refactor with no behavior change (patch version bump)" + "skip-changelog|cccccc|Exclude from release notes" +) + +for entry in "${labels[@]}"; do + IFS='|' read -r name color description <<< "$entry" + gh label create "$name" --color "$color" --description "$description" --force + echo "synced: $name" +done