chore(merge): update starbase (2026-10-20)

.editorconfig

@@ -36,3 +36,6 @@ max_line_length = off
 
 [{*.yaml,*.yml}]
 indent_size = 2
+
+[*.toml]
+indent_size = 2

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,5 +1,10 @@
-- [ ] Have you followed the guidelines for contributing?
-- [ ] Have you signed the [CLA](http://www.ubuntu.com/legal/contributors/)?
-- [ ] Have you successfully run `make lint && make test`?
+Describe your changes.
 
 ---
+
+- [ ] I've followed the [contribution guidelines](https://github.com/canonical/craft-cli/blob/main/CONTRIBUTING.md).
+- [ ] I've signed the [CLA](http://www.ubuntu.com/legal/contributors/).
+- [ ] I've successfully run `make lint && make test`.
+- [ ] I've added or updated any relevant documentation.
+- [ ] In documents I changed, I [added a meta description](https://canonical-starflow.readthedocs-hosted.com/how-to/add-a-page-meta-description/) if one was missing.
+- [ ] I've updated the relevant release notes.

.github/actionlint.yaml

@@ -0,0 +1,28 @@
+# Configuration related to self-hosted runner.
+self-hosted-runner:
+  # Labels of self-hosted runner in array of strings.
+  labels:
+    - spread-enabled
+    - spread-installed
+    # Architectures
+    - amd64
+    - arm64
+    - ppc64el
+    - riscv64
+    - s390x
+    # Ubuntu releases
+    - focal
+    - jammy
+    - noble
+    - resolute
+    # Sizes
+    - medium
+    - large
+    - xlarge
+    - 2xlarge
+    - 2xlarge-extra
+    # Additional possible labels
+    - edge
+    - tiobe
+    - large-tiobe
+    - 2xlarge-tiobe

.github/workflows/check-renovate.yaml

@@ -17,17 +17,24 @@ on:
 jobs:
   renovate:
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
     steps:
       - name: Checkout
-        uses: actions/checkout@v7
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
       - name: Install node
-        uses: actions/setup-node@v7
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
           node-version: 24
+      - name: Install uv
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
       - name: Install renovate
+        # zizmor: ignore[adhoc-packages] renovate is installed ad-hoc here to validate its own config; there is no lockfile for this ephemeral tool.
         run: npm install --global re2 renovate
       - name: Enable ssh access
-        uses: mxschmitt/action-tmate@v3
+        uses: mxschmitt/action-tmate@35b54afac29c97fb54faba5b513f8fbd1882f113 # v3.24
         if: ${{ inputs.enable_ssh_access }}
         with:
           limit-access-to-actor: true

.github/workflows/copilot-setup-steps.yaml

@@ -0,0 +1,75 @@
+name: Copilot Setup Steps
+
+on:
+  workflow_dispatch:
+  push:
+    paths:
+      - .github/workflows/copilot-setup-steps.yaml
+  pull_request:
+    paths:
+      - .github/workflows/copilot-setup-steps.yaml
+
+jobs:
+  copilot-setup-steps:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Set up Node.js
+        uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+        with:
+          node-version: 24
+          cache: npm
+          cache-dependency-path: common.mk
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
+        with:
+          enable-cache: true
+          cache-dependency-glob: |
+            pyproject.toml
+            uv.lock
+
+      - name: Install release tools
+        uses: taiki-e/install-action@8cca0918f8471c33515202b73f56ab27f2bed283 # v2.87.29
+        with:
+          tool: |
+            osv-scanner
+            prek
+            shellcheck
+            shfmt
+            tombi
+            zizmor
+          fallback: none
+
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install --yes \
+            libxml2-dev \
+            libxslt1-dev
+
+      - name: Install actionlint
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          mkdir -p "$HOME/.local/bin"
+          gh release download \
+            --repo rhysd/actionlint \
+            --pattern 'actionlint_*_linux_amd64.tar.gz' \
+            --output /tmp/actionlint.tar.gz \
+            --clobber
+          tar -xzf /tmp/actionlint.tar.gz -C "$HOME/.local/bin" actionlint
+          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
+
+      - name: Prepare git configuration
+        run: git config --local --unset-all core.hooksPath || true
+
+      - name: Set up remaining repository tooling
+        run: make setup

.github/workflows/policy.yaml

@@ -10,10 +10,19 @@ on:
 jobs:
   policy:
     permissions:
-      contents: read
       actions: read
+      contents: read
       security-events: write
     uses: canonical/starflow/.github/workflows/policy.yaml@main
   python-scans:
     name: Security scan
+    permissions:
+      contents: read
     uses: canonical/starflow/.github/workflows/scan-python.yaml@main
+    with:
+      osv-extra-args: "--config=osv-scanner.toml"
+      osv-exclude-paths: |
+        docs
+      uv-export-no-groups: |
+        docs
+        docs-sphinx-stack

.github/workflows/release-publish.yaml

@@ -3,70 +3,79 @@ on:
   push:
     tags:
       # These tags should be protected, remember to enable the rule:
-      # https://github.com/canonical/craft-cli/settings/tag_protection
+      # https://github.com/canonical/starbase/settings/tag_protection
       - "[0-9]+.[0-9]+.[0-9]+"
-
-permissions:
-  contents: write
+  pull_request:
+    paths:
+      - .github/workflows/release-publish.yaml
 
 jobs:
   source-wheel:
-    runs-on: [self-hosted]
+    if: github.event_name == 'push' || (github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository)
+    runs-on: [self-hosted, medium, linux]
+    permissions:
+      contents: read
     steps:
       - name: Install uv
         run: |
           sudo snap install --classic astral-uv
-          sudo apt-get install --yes python3-venv
       - name: Checkout
-        uses: actions/checkout@v7
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
       - name: Fetch tag annotations
+        if: ${{ github.event_name != 'pull_request' }}
         run: |
           # Note: we fetch the tags here instead of using actions/checkout's "fetch-tags"
           # because of https://github.com/actions/checkout/issues/1467
           git fetch --force --tags --depth 1
           git describe --dirty --long --match '[0-9]*.[0-9]*.[0-9]*' --exclude '*[^0-9.]*'
       - name: Build packages
         run: |
-          uv venv --no-managed-python
-          uv pip install build twine
-          uv run -m build
-          uv run twine check dist/*
+          uv build
+          uvx twine check dist/*
       - name: Upload pypi packages artifact
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
         with:
           name: pypi-packages
           path: dist/
+  # NOTE: This PyPI publishing job is often unnecessary for most applications
+  # that use starbase. Please ensure this job is excluded from merges/PRs
+  # originating from starbase unless explicitly required for a specific app.
   pypi:
     needs: ["source-wheel"]
-    runs-on: [self-hosted, amd64]
+    runs-on: [self-hosted, amd64, medium, linux]
     permissions:
       # IMPORTANT: this permission is mandatory for trusted publishing
       id-token: write
     steps:
       - name: Get packages
-        uses: actions/download-artifact@v8
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
         with:
           name: pypi-packages
           path: dist/
       - name: Publish to pypi
+        # Only actually push to pypi when we're on a tag.
+        if: ${{ startsWith(github.ref, 'refs/tags/') }}
         # Note: this action uses PyPI's support for Trusted Publishers
         # It needs a configuration on the PyPI project - see:
         # https://docs.pypi.org/trusted-publishers/adding-a-publisher/#github-actions
-        uses: pypa/gh-action-pypi-publish@release/v1
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1
   github-release:
     needs: ["source-wheel"]
-    runs-on: [self-hosted]
+    runs-on: [self-hosted, medium, linux]
+    permissions:
+      contents: write
     steps:
       - name: Get pypi artifacts
-        uses: actions/download-artifact@v8
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
         with:
           name: pypi-packages
       - name: Release
-        uses: softprops/action-gh-release@v3
-        with:
-          # Generate release notes on the new GH release
-          generate_release_notes: true
-          # Add wheel and source tarball
-          files: |
-            *.whl
-            *.tar.gz
+        # Only actually publish the Github release when we're on a tag.
+        if: ${{ startsWith(github.ref, 'refs/tags/') }}
+        env:
+          GH_REPO: ${{ github.repository }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: gh release create "$RELEASE_TAG" --generate-notes -- *.whl *.tar.gz

.github/workflows/tics.yaml

@@ -3,12 +3,15 @@ on:
   push:
     branches:
       - "main"
-      # For debugging
-      - "work/tiobe*"
+      # For troubleshooting
+      - "work/tiobe**"
 
 jobs:
   TICS:
+    permissions:
+      contents: read
     uses: canonical/starflow/.github/workflows/tics.yaml@main
     with:
       project: "craft-cli"
-    secrets: inherit
+    secrets:
+      TICSAUTHTOKEN: ${{ secrets.TICSAUTHTOKEN }}

.github/zizmor.yaml

@@ -0,0 +1,5 @@
+rules:
+  unpinned-uses:
+    config:
+      policies: # Allow unpinned references to starflow.
+        canonical/starflow/*: ref-pin

.gitignore

@@ -16,7 +16,8 @@ eggs/
 .eggs/
 lib/
 lib64/
-parts/
+# Only top level parts dir, otherwise this conflicts with inner dirs called parts.
+/parts/
 sdist/
 var/
 wheels/
@@ -72,6 +73,8 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/_linkcheck/
+docs/reference/gen/
 docs/spelling/
 
 # PyBuilder
@@ -144,8 +147,12 @@ dmypy.json
 # Ignore version module generated by setuptools_scm
 /*/_version.py
 
-# Visual Studio Code
-.vscode/
-
+# IDE configs
+# VS Code/Codium
+/.vscode/
 # JetBrains IDEs
 /.idea/
+# Zed
+/.zed/
+# KDevelop
+/.kdev4/

.pre-commit-config.yaml

@@ -24,5 +24,11 @@ repos:
     rev: "" # Intentionally blank, despite the warning.
     hooks:
       - id: prettier
+        files: ^(.\/?)*\.(yaml|yml|json|json5|css|md)$
         additional_dependencies:
-          - prettier@3.4.2
+          - prettier@3.6.0 # renovate: datasource=npm
+  - repo: https://github.com/scop/pre-commit-shfmt
+    rev: "v3.13.1-1"
+    hooks:
+      - id: shfmt
+        exclude: '\.sh\.j2$'

AGENTS.md

@@ -64,6 +64,12 @@ make docs
 make lint-docs
 ```
 
+Run documentation targets from the repository root using `make docs-<target>`;
+never invoke the docs Makefile directly, with `make -C`, or equivalent, as it
+bypasses required configuration. Use `make docs-help` to list targets. This
+applies only to commands you run directly, not those triggered via repo
+tooling.
+
 ## Practices
 
 - Backward compatibility is a **hard requirement**. Apps using this library must

Makefile

@@ -10,10 +10,13 @@ UV_TICS_GROUPS := "--group=tics"
 include common.mk
 
 .PHONY: format
-format: format-ruff format-codespell format-prettier  ## Run all automatic formatters
+format: format-ruff format-codespell format-prettier format-shfmt format-tombi format-pre-commit  ## Run all automatic formatters
 
 .PHONY: lint
-lint: lint-ruff lint-ty lint-codespell lint-prettier lint-shellcheck lint-docs lint-twine  ## Run all linters
+lint: lint-code lint-docs lint-twine lint-uv-lockfile lint-actions  ## Run all linters
+
+.PHONY: lint-code
+lint-code: lint-ruff lint-ty lint-codespell lint-prettier lint-shfmt lint-shellcheck lint-tombi  ## Run code-specific linters
 
 .PHONY: pack
 pack: pack-pip  ## Build all packages
@@ -44,17 +47,3 @@ endif
 # If additional build dependencies need installing in order to build the linting env.
 .PHONY: install-lint-build-deps
 install-lint-build-deps: install-ty
-
-.PHONY: lint-ty
-lint-ty: install-ty
-	ty check
-
-.PHONY: install-ty
-install-ty:
-ifneq ($(shell which ty),)
-else ifneq ($(shell which snap),)
-	sudo snap install --beta astral-ty
-	sudo snap alias astral-ty.ty ty
-else ifneq ($(shell which uv),)
-	uv tool install ty
-endif