Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 4 additions & 5 deletions .devcontainer/Dockerfile
Original file line number Diff line number Diff line change
@@ -1,22 +1,21 @@
# 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 \
# && apt-get -y install --no-install-recommends <your-package-list-here>

# [Optional] Uncomment this line to install global node packages.
# RUN su vscode -c "source /usr/local/share/nvm/nvm.sh && npm install -g <your-package-here>" 2>&1

5 changes: 1 addition & 4 deletions .devcontainer/devcontainer.json
Original file line number Diff line number Diff line change
Expand Up @@ -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"
}
Expand Down
46 changes: 46 additions & 0 deletions .github/dependabot.yml
Original file line number Diff line number Diff line change
@@ -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"]
26 changes: 9 additions & 17 deletions .github/workflows/python.yml
Original file line number Diff line number Diff line change
@@ -1,36 +1,28 @@
name: CI Checks
name: Python CI Checks

on:
push:
branches: [ main ]
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: |
Expand Down
10 changes: 5 additions & 5 deletions .github/workflows/release-drafter.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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
Expand Down
12 changes: 7 additions & 5 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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 }}

Expand All @@ -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 }}
Expand Down
38 changes: 38 additions & 0 deletions .github/workflows/security.yml
Original file line number Diff line number Diff line change
@@ -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
1 change: 1 addition & 0 deletions Brewfile
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
brew "gitleaks"
brew "just"
brew "uv"
brew "zizmor"
24 changes: 24 additions & 0 deletions CLAUDE.md.example
Original file line number Diff line number Diff line change
Expand Up @@ -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 <pkg>` / `uv add --dev <pkg>` - add a runtime / dev dependency (never edit `uv.lock` by hand)
- `uv run example` - run the app entry point

Expand All @@ -19,10 +23,30 @@ 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.<module> 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

- Python >= 3.14; ruff line length 100, double quotes
- 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/<name>/` folder, and `[project.scripts]` together

## CI, security, and releases

- Pin GitHub Actions to a full commit SHA with a version comment (`uses: owner/action@<sha> # 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:<digest>`
- 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`
28 changes: 25 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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

Expand All @@ -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),
Expand All @@ -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
Expand Down
7 changes: 7 additions & 0 deletions justfile
Original file line number Diff line number Diff line change
Expand Up @@ -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
4 changes: 2 additions & 2 deletions pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand Down Expand Up @@ -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"
Loading
Loading