shipmill 0.31.0__tar.gz

shipmill-0.31.0/.claude/settings.json

@@ -0,0 +1,14 @@
+{
+  "extraKnownMarketplaces": {
+    "shipmill": {
+      "source": {
+        "source": "github",
+        "repo": "shipmill/shipmill"
+      },
+      "autoUpdate": true
+    }
+  },
+  "enabledPlugins": {
+    "shipmill@shipmill": true
+  }
+}

shipmill-0.31.0/.claude-plugin/marketplace.json

@@ -0,0 +1,17 @@
+{
+  "name": "shipmill",
+  "owner": {
+    "name": "Roman Medvedev",
+    "email": "pypi@romavm.dev"
+  },
+  "metadata": {
+    "description": "The shipmill plugin: GitHub issue triage, PR landing, and release lanes"
+  },
+  "plugins": [
+    {
+      "name": "shipmill",
+      "source": "./",
+      "description": "Issue to release on GitHub: triage issues, review and land pull requests, and cut releases on lanes from a hand-written CHANGELOG"
+    }
+  ]
+}

shipmill-0.31.0/.claude-plugin/plugin.json

@@ -0,0 +1,19 @@
+{
+  "name": "shipmill",
+  "version": "0.31.0",
+  "description": "Issue to release on GitHub: triage issues, review and land pull requests, and cut releases on lanes from a hand-written CHANGELOG",
+  "author": {
+    "name": "Roman Medvedev",
+    "email": "pypi@romavm.dev"
+  },
+  "homepage": "https://github.com/shipmill/shipmill",
+  "repository": "https://github.com/shipmill/shipmill",
+  "license": "MIT",
+  "keywords": [
+    "github",
+    "triage",
+    "pull-requests",
+    "release",
+    "changelog"
+  ]
+}

shipmill-0.31.0/.github/shipmill.toml

@@ -0,0 +1,53 @@
+# shipmill releases itself with its own workflows, at the commit being released
+name = "shipmill"
+mode = "release"
+branch = "main"
+version_files = "pyproject"
+after_stamp = ["uv lock --check"]
+
+[changelog]
+style = "keep-a-changelog"
+
+[bump]
+from = "headings"
+major = ["Breaking"]
+minor = ["Added", "Changed", "Deprecated", "Removed"]
+patch = ["Fixed", "Security"]
+
+[gates]
+blocker_label = "release-blocker"
+blocker_lanes = ["stable"]
+
+# A stable release after every batch of merges, and hotfixes by hand
+[lanes.stable]
+quiet_minutes = 30
+github_release = true
+dispatch = ["move-major-tag.yml", "publish.yml"]  # publish.yml: PyPI (spec 010)
+
+[lanes.hotfix]
+github_release = true
+dispatch = ["publish.yml"]
+
+# The plugin's version follows the package's, so a plugin update ships with each release
+[[version_lines]]
+file = ".claude-plugin/plugin.json"
+pattern = '"version": "[^"]+"'
+replace = '"version": "{version}"'
+
+# shipmill's own GitHub Pages site: each stable release deploys there, and operate checks that
+# its health.json names the deployed release (#53)
+[environments.github-pages]
+lane = "stable"
+workflow = "deploy.yml"
+health = "https://shipmill.github.io/shipmill/health.json"
+
+[operate]
+rollback_after = 3
+
+# shipmill's own gate: a background session triages new issues and lands green PRs
+[agents]
+prompt = "/github-issue-triage {repo} triage the new issues; merge when green"
+prs = true
+retry_hours = 24
+app_id = 5209412   # gated sessions write as shipmill-romamo[bot] (spec 004)
+mode = "headless"  # what the gate runs; written out, not left to the default (D-20)

shipmill-0.31.0/.github/workflows/ci.yml

@@ -0,0 +1,49 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+  workflow_call: # shipmill's Release workflow runs it on its release commit
+    inputs:
+      ref:
+        type: string
+        required: true
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: ${{ inputs.ref }} # empty outside workflow_call: the event's commit
+
+      - uses: astral-sh/setup-uv@v10.2.0
+        with:
+          python-version: "3.14"
+
+      - run: uv sync --locked
+      - run: uv run ruff check src tests skills
+      - run: uv run ruff format --check src tests skills
+      - run: uv run mypy
+      - run: uv run pytest -q
+      - name: Check the specs, and that a test proves each criterion of a built one
+        run: |
+          uv run --no-project python skills/github-issue-triage/scripts/specs.py check
+          uv run --no-project python skills/github-issue-triage/scripts/specs.py coverage
+      - name: Lint the workflows, including the template init writes
+        run: |
+          uvx --from actionlint-py actionlint .github/workflows/*.yml
+          uv run python -c "
+          from shipmill.init import Detected, caller_text
+          from shipmill.policy import Style, VersionFiles
+          print(caller_text(Detected('demo', 'main', Style.KEEP_A_CHANGELOG, VersionFiles.NONE), 'ci.yml'))
+          " > "$RUNNER_TEMP/release.yml"
+          uvx --from actionlint-py actionlint -ignore 'ci.yml' "$RUNNER_TEMP/release.yml"
+          uv run python -c "from shipmill.init import operate_caller_text; print(operate_caller_text())" \
+            > "$RUNNER_TEMP/operate.yml"
+          uvx --from actionlint-py actionlint "$RUNNER_TEMP/operate.yml"

shipmill-0.31.0/.github/workflows/deploy.yml

@@ -0,0 +1,107 @@
+name: Deploy
+
+# shipmill's own deploy target: GitHub Pages at https://shipmill.github.io/shipmill/. land
+# starts it on each stable tag, and shipmill operate on a rollback, with -f tag=<tag>
+# -f environment=github-pages; by hand, run it on the tag too (--ref <tag>), or it fails. The site is site/ at the tag plus a health.json naming the
+# release, {"version": "X.Y.Z"}, which shipmill operate checks against the deployed tag.
+
+on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "The release tag to deploy, such as v1.2.0"
+        type: string
+        required: true
+      environment:
+        description: "The GitHub environment; Pages deploys only to github-pages"
+        type: string
+        required: true
+      simulate-failure:
+        # The rollback drill's fault (#53): health.json names a version that isn't the tag, so
+        # operate's health check fails and it rolls back, without shipping a broken package.
+        # Nothing but the drill sets it
+        description: "Rollback drill only: health.json reports a version that isn't the tag"
+        type: boolean
+        default: false
+
+permissions:
+  contents: read
+
+# One Pages deploy at a time, none cancelled: a rollback must not be dropped mid-way
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check the inputs
+        env:
+          TAG: ${{ inputs.tag }}
+          ENVIRONMENT: ${{ inputs.environment }}
+        run: |
+          if [ "$ENVIRONMENT" != "github-pages" ]; then
+            echo "::error::environment must be github-pages, got '$ENVIRONMENT'"
+            exit 1
+          fi
+          if ! [[ "$TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+[0-9A-Za-z.+-]*$ ]]; then
+            echo "::error::tag must be a release tag such as v1.2.0, got '$TAG'"
+            exit 1
+          fi
+          # GitHub records the deployment under the run's ref, which operate reads as the tag
+          # that runs there (#80): a run started without --ref <tag> would record a branch
+          if [ "$GITHUB_REF" != "refs/tags/$TAG" ]; then
+            echo "::error::run deploy.yml on the tag it deploys, not $GITHUB_REF:" \
+              "gh workflow run deploy.yml --ref $TAG -f tag=$TAG -f environment=$ENVIRONMENT"
+            exit 1
+          fi
+
+      - uses: actions/checkout@v7
+        with:
+          ref: refs/tags/${{ inputs.tag }}
+
+      - name: Write health.json
+        env:
+          TAG: ${{ inputs.tag }}
+          SIMULATE_FAILURE: ${{ inputs.simulate-failure }}
+        run: |
+          version="${TAG#v}"
+          if [ "$SIMULATE_FAILURE" = "true" ]; then
+            version="0.0.0-simulated-failure"
+          fi
+          printf '{"version": "%s"}\n' "$version" > site/health.json
+          cat site/health.json
+
+      - uses: actions/upload-pages-artifact@v5
+        with:
+          path: site/
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write # deploys the artifact
+      id-token: write # proves the deploy comes from this workflow
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v5
+
+  # The first health check right after the deploy, not at the next scheduled operate run
+  # (#84); the schedule stays the backstop. A job of its own: a failure here leaves the
+  # deployment's success alone. operate deploys a tag to an environment at most once, so a
+  # run it starts never deploys this tag again, nor races land's dispatch
+  operate:
+    needs: deploy
+    runs-on: ubuntu-latest
+    permissions:
+      actions: write # starts operate-self.yml
+    steps:
+      - name: Start shipmill operate
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+        run: gh workflow run operate-self.yml -f dry-run=false

shipmill-0.31.0/.github/workflows/land.yml

@@ -0,0 +1,107 @@
+name: shipmill land
+
+# Called after the caller's CI ran on the release commit. When CI passed it lands the
+# release: main (a stable release on an unmoved main), release/X.Y (a hotfix), or the tag
+# alone (a pre-release, or a stable release promoted while main moved on, which then gets a
+# sync commit on main). It tags, publishes, and starts the lane's dispatch workflows.
+# Whatever happened, the work branch is deleted: a failed release is planned again. Under
+# release = "propose" it then closes the lane's proposal issue.
+
+on:
+  workflow_call:
+    inputs:
+      ci-result:
+        type: string
+        required: true
+      lane:
+        type: string
+        required: true
+      version:
+        type: string
+        required: true
+      sha:
+        type: string
+        required: true
+      base:
+        type: string
+        required: true
+      tool:
+        type: string
+        default: "git+https://github.com/shipmill/shipmill@v0"
+
+# No workflow-level permissions: each job sets its own, except close-proposal, which takes
+# the caller's grant, so a caller that grants no `issues: write` still starts this workflow
+
+jobs:
+  land:
+    if: inputs.ci-result == 'success'
+    concurrency:
+      group: shipmill
+      cancel-in-progress: false
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write # main, release branches, tags, and releases
+      actions: write # starts dispatch workflows; a push with this token starts none
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: ${{ github.event.repository.default_branch }}
+          fetch-depth: 0
+
+      - uses: astral-sh/setup-uv@v10.2.0
+
+      - name: Land, tag, and publish
+        shell: bash # -eo pipefail: a failed land fails the step, though its output goes through tee
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TOOL: ${{ inputs.tool }}
+          LANE: ${{ inputs.lane }}
+          VERSION: ${{ inputs.version }}
+          SHA: ${{ inputs.sha }}
+          BASE: ${{ inputs.base }}
+        run: |
+          uvx --from "$TOOL" shipmill land --lane "$LANE" --version "$VERSION" --sha "$SHA" --base "$BASE" \
+            | tee -a "$GITHUB_STEP_SUMMARY"
+
+  # Closes the lane's "Ready to release" issue, with the tag and this run. It sets no
+  # permissions, so it runs with the caller's grant: under release = "propose" closing needs
+  # `issues: write` on the caller's land job; without it this job fails, after the release
+  # landed. Under any other release autonomy it reads nothing from GitHub
+  close-proposal:
+    needs: land
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: ${{ github.event.repository.default_branch }}
+
+      - uses: astral-sh/setup-uv@v10.2.0
+
+      - name: Close the lane's proposal issue
+        shell: bash # -eo pipefail: a failed close fails the step, though its output goes through tee
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TOOL: ${{ inputs.tool }}
+          LANE: ${{ inputs.lane }}
+          VERSION: ${{ inputs.version }}
+        run: |
+          uvx --from "$TOOL" shipmill close-proposal --lane "$LANE" --version "$VERSION" | tee -a "$GITHUB_STEP_SUMMARY"
+
+  cleanup:
+    needs: land
+    if: always()
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: ${{ github.event.repository.default_branch }}
+
+      - uses: astral-sh/setup-uv@v10.2.0
+
+      - name: Delete the work branch
+        env:
+          TOOL: ${{ inputs.tool }}
+          VERSION: ${{ inputs.version }}
+        run: uvx --from "$TOOL" shipmill cleanup --version "$VERSION"

shipmill-0.31.0/.github/workflows/move-major-tag.yml

@@ -0,0 +1,35 @@
+name: Move the major tag
+
+# Callers pin `@v0`: after a stable release, point the major tag at it. shipmill's land
+# workflow starts this one with the release's tag.
+
+on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "The release tag, such as v0.2.0"
+        type: string
+        required: true
+
+permissions:
+  contents: write
+
+jobs:
+  move:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - name: Point the major tag at the release
+        env:
+          TAG: ${{ inputs.tag }}
+        run: |
+          if ! [[ "$TAG" =~ ^v([0-9]+)\.[0-9]+\.[0-9]+$ ]]; then
+            echo "::error::$TAG is not a stable vX.Y.Z tag"
+            exit 1
+          fi
+          major="v${BASH_REMATCH[1]}"
+          git tag -f "$major" "$TAG^{commit}"
+          git push -f origin "refs/tags/$major"

shipmill-0.31.0/.github/workflows/operate-self.yml

@@ -0,0 +1,44 @@
+name: Operate
+
+# shipmill dogfoods itself: the caller `shipmill init --operate` writes, but calling the
+# reusable operate.yml in this repository (whose name it takes) and running the tool from the
+# checkout. Every 10 minutes shipmill operate checks the health of each environment in
+# .github/shipmill.toml, records it as GitHub deployment statuses, and rolls back an
+# environment that fails its checks, opening an incident issue. Approve a deploy that waits
+# on a proposal issue with: gh workflow run operate-self.yml -f approve=<environment> -f
+# dry-run=false; a proposed rollback with -f approve-rollback=<environment> instead
+
+on:
+  schedule:
+    - cron: "*/10 * * * *"
+  workflow_dispatch:
+    inputs:
+      approve:
+        description: "Deploy the tag proposed for this environment, once"
+        type: string
+        default: ""
+      approve-rollback:
+        description: "Start the rollback an incident proposes for this environment, once"
+        type: string
+        default: ""
+      dry-run:
+        description: "Show what it would do, change nothing"
+        type: boolean
+        default: true
+
+permissions:
+  contents: read
+
+jobs:
+  operate:
+    uses: ./.github/workflows/operate.yml
+    with:
+      approve: ${{ inputs.approve || '' }}
+      approve-rollback: ${{ inputs.approve-rollback || '' }}
+      dry-run: ${{ inputs.dry-run || false }}
+      tool: "."
+    permissions:
+      contents: read # the config and the release tags
+      deployments: write # reads deployments and records health as their statuses
+      actions: write # starts the deploy workflows
+      issues: write # the hold, the issue a deploy under propose or the hold opens, and incidents

shipmill-0.31.0/.github/workflows/operate.yml

@@ -0,0 +1,61 @@
+name: shipmill operate
+
+# Called on a schedule by a repository's operate workflow (see `shipmill init --operate`).
+# It checks the health of each environment in [environments], records it as GitHub
+# deployment statuses, and promotes a release to an environment with `from` once its source
+# baked it (or opens the issue a deploy under propose or a hold waits on). An environment
+# failing [operate] rollback_after checks in a row is rolled back and gets an incident issue.
+# With `approve`, it deploys the tag proposed for that environment, once, instead; with
+# `approve-rollback`, it starts the rollback an incident proposes for it, once.
+
+on:
+  workflow_call:
+    inputs:
+      approve:
+        description: "An environment whose proposed deploy to run; empty runs the checks"
+        type: string
+        default: ""
+      approve-rollback:
+        description: "An environment whose proposed rollback to start; empty runs the checks"
+        type: string
+        default: ""
+      dry-run:
+        type: boolean
+        default: false
+      tool:
+        description: "Where uvx installs shipmill from"
+        type: string
+        default: "git+https://github.com/shipmill/shipmill@v0"
+
+# No permissions here or on the job: it runs with the caller's grant, as a reusable job that
+# asks for more than its caller grants fails to start. It needs contents: read, deployments:
+# write, actions: write, and issues: write to open a proposal or an incident issue
+
+jobs:
+  operate:
+    # One operate at a time: a run that overlapped the previous one could deploy twice
+    concurrency:
+      group: shipmill-operate
+      cancel-in-progress: false
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: ${{ github.event.repository.default_branch }}
+          fetch-depth: 0 # the release tags, to tell a missed deploy
+
+      - uses: astral-sh/setup-uv@v10.2.0
+
+      - name: Operate
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TOOL: ${{ inputs.tool }}
+          APPROVE: ${{ inputs.approve }}
+          APPROVE_ROLLBACK: ${{ inputs.approve-rollback }}
+          DRY_RUN: ${{ inputs.dry-run && '--dry-run' || '' }}
+        run: |
+          args=(operate)
+          [ -n "$APPROVE" ] && args+=(--approve "$APPROVE")
+          [ -n "$APPROVE_ROLLBACK" ] && args+=(--approve-rollback "$APPROVE_ROLLBACK")
+          [ -n "$DRY_RUN" ] && args+=(--dry-run)
+          uvx --from "$TOOL" shipmill "${args[@]}"