ehanson8 · Aug 18, 2026 · Aug 12, 2026 · Aug 12, 2026
@@ -15,16 +15,6 @@ YES | NO
 ### What are the relevant tickets?
 - Include links to Jira Software and/or Jira Service Management tickets here.
 
-### Developer
-- [ ] All new ENV is documented in README
-- [ ] All new ENV has been added to staging and production environments
-- [ ] All related Jira tickets are linked in commit message(s)
-- [ ] Stakeholder approval has been confirmed (or is not needed)
-
-### Code Reviewer(s)
-- [ ] The commit message is clear and follows our guidelines (not just this PR message)
-- [ ] There are appropriate tests covering any new functionality
-- [ ] The provided documentation is sufficient for understanding any new functionality introduced
-- [ ] Any manual tests have been performed **or** provided examples verified
-- [ ] New dependencies are appropriate or there were no changes
+### Code review
+* Code review best practices are documented [here](https://mitlibraries.github.io/guides/collaboration/code_review.html) and you are encouraged to have a constructive dialogue with your reviewers about their preferences and expectations.
 
@@ -1,46 +1,11 @@
 name: CI
+permissions: read-all
 on:
   pull_request:
     paths-ignore:
       - '.github/**'
 jobs:
   test:
-    # TODO: move this into a shared workflow, https://github.com/MITLibraries/.github/tree/main/.github/workflows
-    name: Run tests and report coverage
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Install uv
-        uses: astral-sh/setup-uv@v6
-
-      - name: Create virtual environment
-        run: |
-          make install
-
-      - name: Run tests and make coverage report
-        run: |
-          make test
-          make coveralls
-
-      - name: Coveralls
-        uses: coverallsapp/github-action@v2.3.0
-        with:
-          github-token: ${{ secrets.GITHUB_TOKEN }}
-          fail-on-error: false
+    uses: mitlibraries/.github/.github/workflows/python-uv-shared-test.yml@main
   lint:
-    # TODO: move this into a shared workflow, https://github.com/MITLibraries/.github/tree/main/.github/workflows
-    name: Run linters
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Install uv
-        uses: astral-sh/setup-uv@v6
-
-      - name: Create virtual environment
-        run: |
-          make install
-
-      - name: Lint
-        run: make lint
+    uses: mitlibraries/.github/.github/workflows/python-uv-shared-lint.yml@main
@@ -157,5 +157,5 @@ output/
 .vscode/
 
 AGENTS.md
-
-.arch_tag
+.arch_tag
+.tool-versions
@@ -1,29 +1,30 @@
 default_language_version:
   python: python3.13
+
+default_stages:
+  - pre-push
+
 repos:
   - repo: local
     hooks:
-      - id: black-apply
-        name: black-apply
-        entry: uv run black
+      - id: ruff-format
+        name: ruff-format
+        entry: uv run ruff format --diff
         language: system
         pass_filenames: true
         types: ["python"]
+
       - id: mypy
         name: mypy
         entry: uv run mypy
         language: system
         pass_filenames: true
         types: ["python"]
-        exclude: "tests/"
-      - id: ruff-apply
-        name: ruff-apply
-        entry: uv run ruff check --fix
+        exclude: "(tests/|output/|migrations/)"
+
+      - id: ruff-check
+        name: ruff-check
+        entry: uv run ruff check
         language: system
         pass_filenames: true
         types: ["python"]
-      - id: pip-audit
-        name: pip-audit
-        entry: uv run pip-audit --ignore-vuln GHSA-4xh5-x5gv-qwph
-        language: system
-        pass_filenames: false
@@ -6,28 +6,33 @@ ECR_URL_DEV := 222053980223.dkr.ecr.us-east-1.amazonaws.com/marimo-launcher-dev
 CPU_ARCH ?= $(shell cat .aws-architecture 2>/dev/null || echo "linux/amd64")
 ### End of Terraform-generated header                                   ###
 
+CPU_ARCH ?= $(shell cat .aws-architecture 2>/dev/null || echo "linux/amd64")
 
 help: # Preview Makefile commands
 	@awk 'BEGIN { FS = ":.*#"; print "Usage:  make <target>\n\nTargets:" } \
 /^[-_[:alpha:]]+:.?*#/ { printf "  %-15s%s\n", $$1, $$2 }' $(MAKEFILE_LIST)
 
 # ensure OS binaries aren't called if naming conflict with Make recipes
-.PHONY: help dist-dev publish-dev dist-stage publish-stage venv install update test coveralls lint black mypy ruff safety lint-apply black-apply ruff-apply
+.PHONY: help dist-dev publish-dev dist-stage publish-stage venv install update test coveralls lint lint-fix security check-arch docker-clean marimo-launcher mypy ruff
 
 ##############################################
 # Python Environment and Dependency commands
 ##############################################
 
-install: .venv .git/hooks/pre-commit # Install Python dependencies and create virtual environment if not exists
+install: .venv .git/hooks/pre-commit .git/hooks/pre-push # Install Python dependencies and create virtual environment if not exists
 	uv sync --dev
 
 .venv: # Creates virtual environment if not found
 	@echo "Creating virtual environment at .venv..."
 	uv venv .venv
 
-.git/hooks/pre-commit: # Sets up pre-commit hook if not setup
-	@echo "Installing pre-commit hooks..."
-	uv run pre-commit install
+.git/hooks/pre-commit: # Sets up pre-commit commit hooks if not setup
+	@echo "Installing pre-commit commit hooks..."
+	uv run pre-commit install --hook-type pre-commit
+
+.git/hooks/pre-push: # Sets up pre-commit push hooks if not setup
+	@echo "Installing pre-commit push hooks..."
+	uv run pre-commit install --hook-type pre-push
 
 venv: .venv # Create the Python virtual environment
 
@@ -47,35 +52,34 @@ coveralls: test # Write coverage data to an LCOV report
 	uv run coverage lcov -o ./coverage/lcov.info
 
 ####################################
-# Code quality and safety commands
+# Code linting and formatting
 ####################################
 
-lint: black mypy ruff safety # Run linters
+lint: # Run linting, alerts only, no code changes
+	uv run ruff format --diff
+	uv run mypy .
+	uv run ruff check .
 
-black: # Run 'black' linter and print a preview of suggested changes
-	uv run black --check --diff .
+lint-fix: # Run linting, auto fix behaviors where supported
+	uv run ruff format .
+	uv run ruff check --fix .
 
-mypy: # Run 'mypy' linter
+mypy: # Run 'mypy' type checker
 	uv run mypy .
 
 ruff: # Run 'ruff' linter and print a preview of errors
 	uv run ruff check .
 
-safety: # Check for security vulnerabilities
-	uv run pip-audit --ignore-vuln GHSA-4xh5-x5gv-qwph
-
-lint-apply: black-apply ruff-apply # Apply changes with 'black' and resolve 'fixable errors' with 'ruff'
-
-black-apply: # Apply changes with 'black'
-	uv run black .
-
-ruff-apply: # Resolve 'fixable errors' with 'ruff'
-	uv run ruff check --fix .
+security: # Run security / vulnerability checks
+	uv run pip-audit
 
 
 ####################################
 # CLI
 ####################################
+marimo-launcher: # CLI without any arguments, utilizing uv script entrypoint
+	uv run marimo-launcher
+
 cli-test-inline-run:
 	uv run marimo-launcher \
     run \
@@ -113,54 +117,51 @@ docker-test-run: # Test local docker container with test fixture notebook
 # Terraform
 ####################################
 
-### Terraform-generated Developer Deploy Commands for Dev environment ###
-check-arch:
-	@ARCH_FILE=".aws-architecture"; \
-	if [[ "$(CPU_ARCH)" != "linux/amd64" && "$(CPU_ARCH)" != "linux/arm64" ]]; then \
-        echo "Invalid CPU_ARCH: $(CPU_ARCH)"; exit 1; \
-    fi; \
-	if [[ -f $$ARCH_FILE ]]; then \
-		echo "latest-$(shell echo $(CPU_ARCH) | cut -d'/' -f2)" > .arch_tag; \
+### Terraform-generated Developer Deploy Commands for Dev environment           ###
+check-arch: # Validate CPU_ARCH and write .arch_tag
+	@if [[ "$(CPU_ARCH)" != "linux/amd64" && "$(CPU_ARCH)" != "linux/arm64" ]]; then \
+		echo "Invalid CPU_ARCH: $(CPU_ARCH)"; exit 1; \
+	fi; \
+	if [[ -f .aws-architecture ]]; then \
+		echo "latest-$$(echo $(CPU_ARCH) | cut -d'/' -f2)" > .arch_tag; \
 	else \
 		echo "latest" > .arch_tag; \
 	fi
 
 dist-dev: check-arch ## Build docker container (intended for developer-based manual build)
-	@ARCH_TAG=$$(cat .arch_tag); \
-	docker buildx inspect $(ECR_NAME_DEV) >/dev/null 2>&1 || docker buildx create --name $(ECR_NAME_DEV) --use; \
-	docker buildx use $(ECR_NAME_DEV); \
+	docker buildx inspect $(ECR_NAME_DEV) >/dev/null 2>&1 || docker buildx create --name $(ECR_NAME_DEV) --use
+	docker buildx use $(ECR_NAME_DEV)
 	docker buildx build --platform $(CPU_ARCH) \
 		--load \
-	    --tag $(ECR_URL_DEV):$$ARCH_TAG \
-	    --tag $(ECR_URL_DEV):make-$$ARCH_TAG \
-		--tag $(ECR_URL_DEV):make-$(shell git describe --always) \
-		--tag $(ECR_NAME_DEV):$$ARCH_TAG \
-		.
+		-t $(ECR_URL_DEV):latest \
+		-t $(ECR_URL_DEV):`git describe --always` \
+		-t $(ECR_NAME_DEV):latest .
 
 publish-dev: dist-dev ## Build, tag and push (intended for developer-based manual publish)
-	@ARCH_TAG=$$(cat .arch_tag); \
-	aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin $(ECR_URL_DEV); \
-	docker push $(ECR_URL_DEV):$$ARCH_TAG; \
-	docker push $(ECR_URL_DEV):make-$$ARCH_TAG; \
-	docker push $(ECR_URL_DEV):make-$(shell git describe --always); \
-    echo "Cleaning up dangling Docker images..."; \
-    docker image prune -f --filter "dangling=true"
-
-
-### If this is a Lambda repo, uncomment the two lines below     ###
-# update-lambda-dev: ## Updates the lambda with whatever is the most recent image in the ecr (intended for developer-based manual update)
-#	@ARCH_TAG=$$(cat .arch_tag); \
-#	aws lambda update-function-code \
-#		--region us-east-1 \
-#		--function-name $(FUNCTION_DEV) \
-#		--image-uri $(ECR_URL_DEV):make-$$ARCH_TAG
-
-docker-clean: ## Clean up Docker detritus
-	@ARCH_TAG=$$(cat .arch_tag); \
-	echo "Cleaning up Docker leftovers (containers, images, builders)"; \
-	docker rmi -f $(ECR_URL_DEV):$$ARCH_TAG; \
-	docker rmi -f $(ECR_URL_DEV):make-$$ARCH_TAG; \
-	docker rmi -f $(ECR_URL_DEV):make-$(shell git describe --always) || true; \
-    docker rmi -f $(ECR_NAME_DEV):$$ARCH_TAG || true; \
+	aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin $(ECR_URL_DEV)
+	docker push $(ECR_URL_DEV):latest
+	docker push $(ECR_URL_DEV):`git describe --always`
+
+### Terraform-generated manual shortcuts for deploying to Stage. This requires  ###
+###   that ECR_NAME_STAGE, ECR_URL_STAGE, and FUNCTION_STAGE environment        ###
+###   variables are set locally by the developer and that the developer has     ###
+###   authenticated to the correct AWS Account. The values for the environment  ###
+###   variables can be found in the stage_build.yml caller workflow.            ###
+dist-stage: ## Only use in an emergency
+	docker buildx build --platform $(CPU_ARCH) \
+		--load \
+	    -t $(ECR_URL_STAGE):latest \
+		-t $(ECR_URL_STAGE):`git describe --always` \
+		-t $(ECR_NAME_STAGE):latest .
+
+publish-stage: ## Only use in an emergency
+	aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin $(ECR_URL_STAGE)
+	docker push $(ECR_URL_STAGE):latest
+	docker push $(ECR_URL_STAGE):`git describe --always`
+
+docker-clean: # Clean up Docker detritus
+	docker rmi -f $(ECR_URL_DEV):latest || true
+	docker rmi -f $(ECR_URL_DEV):`git describe --always` || true
+	docker rmi -f $(ECR_NAME_DEV):latest || true
 	docker buildx rm $(ECR_NAME_DEV) || true
 	@rm -rf .arch_tag
@@ -7,6 +7,8 @@
 - To update dependencies: `make update`
 - To run unit tests: `make test`
 - To lint the repo: `make lint`
+- To auto-fix lint issues: `make lint-fix`
+- To check for security vulnerabilities: `make security`
 - To run the app: `uv run launcher --help`
 
 ## Overview

@@ -15,7 +15,6 @@ dependencies = [
 
 [dependency-groups]
 dev = [
-    "black>=25.1.0",
     "coveralls>=4.0.1",
     "ipython>=9.4.0",
     "mypy>=1.17.1",
@@ -25,9 +24,6 @@ dev = [
     "ruff>=0.12.8",
 ]
 
-[tool.black]
-line-length = 90
-
 [tool.mypy]
 disallow_untyped_calls = true
 disallow_untyped_defs = true
@@ -50,6 +46,7 @@ select = ["ALL", "PT"]
 ignore = [
     "C90",
     "COM812",
+    "CPY001",
     "D100",
     "D101",
     "D102",