✨ Template | CI: Add opt-in copier-update workflow

Generated projects have no automated way to stay in sync with upstream template changes,
leading to silent drift over time.

Add a hidden `auto_update` Copier question (`none`/`github-token`/`pat`) that
conditionally includes a `copier-update.yaml` workflow. The question is hidden (`when:
false`) to keep the interactive prompt minimal — users opt in via `--data` when they
want it. The workflow runs weekly (and on manual dispatch), applies `copier update
--defaults --force`, checks for an existing open PR to avoid duplicates, and opens a new
PR when changes are detected. The `github-token` mode requires zero setup but won't
trigger other workflows due to `GITHUB_TOKEN` limitations; the `pat` mode uses a
repository secret so that PRs trigger downstream CI normally.

Author: mbercx

README.md

@@ -17,6 +17,7 @@ Template for Python packages based on [`copier`](https://copier.readthedocs.io/e
     * Deploy documentation to [GitHub Pages](https://docs.github.com/en/pages/getting-started-with-github-pages/creating-a-github-pages-site) or [Read the Docs](https://about.readthedocs.com/).
     * Run pre-commit checks and tests on every pull request.
     * Publish to [PyPI](https://pypi.org/) on `vX.Y.Z` tags via [Trusted Publishing](https://docs.pypi.org/trusted-publishers/) — no API tokens.
+    * Optional automatic template updates via a bot.
 
 ## Usage
 

copier.yml

@@ -40,6 +40,18 @@ coverage:
     - codecov
   default: none
 
+# github-token: uses the default GITHUB_TOKEN (zero setup, but PRs won't trigger CI).
+# pat: uses a PAT stored as COPIER_UPDATE_TOKEN secret (PRs trigger CI normally).
+auto_update:
+  type: str
+  help: 'How should automatic template updates be configured?'
+  choices:
+    - none
+    - github-token
+    - pat
+  default: none
+  when: false
+
 _subdirectory: template
 _message_after_copy: |
   The `{{package_name}}` package has been created successfully!

docs/index.md

@@ -15,6 +15,7 @@ A `copier`-based template for Python packages.
     * Deploy documentation to [GitHub Pages](https://docs.github.com/en/pages/getting-started-with-github-pages/creating-a-github-pages-site) or [Read the Docs](https://about.readthedocs.com/).
     * Run pre-commit checks and tests on every pull request.
     * Publish to [PyPI](https://pypi.org/) on `vX.Y.Z` tags via [Trusted Publishing](https://docs.pypi.org/trusted-publishers/) — no API tokens.
+    * Optional automatic template updates via a bot.
 
 ## Usage
 
@@ -46,3 +47,29 @@ You don't have to publish right away, but if you care about the project name, pu
 2. Go to [Read the Docs](https://readthedocs.org/) (RTD) and [import your project](https://docs.readthedocs.com/platform/stable/tutorial/index.html#importing-the-project-to-read-the-docs).
    The build will use the included `.readthedocs.yaml` automatically.
 3. Set the RTD settings to [build from GitHub pull requests](https://docs.readthedocs.com/platform/stable/tutorial/index.html#triggering-builds-from-pull-requests).
+
+### Coverage with Codecov
+
+If you selected `coverage=codecov` when generating, the CI workflow uploads coverage data to [Codecov](https://about.codecov.io/) after every test run.
+To get this working:
+
+1. Sign up at [codecov.io](https://codecov.io/) and connect your GitHub account.
+2. Add your repository on the Codecov dashboard — it will start receiving uploads automatically.
+
+No repository secret is needed for public repos.
+For private repos, add a `CODECOV_TOKEN` secret to your repository and pass it in the workflow's `codecov-action` step.
+
+### Automatic template updates
+
+The template can optionally add a `copier-update.yaml` workflow that checks for upstream template changes every week, runs `copier update`, and opens a PR with the proposed changes.
+This feature is controlled by the hidden `auto_update` question (set via `--data auto_update=<value>` when copying or updating):
+
+- `none` (default) — no workflow is added.
+- `github-token` — uses the default `GITHUB_TOKEN`. Zero setup, but PRs created this way [won't trigger other CI workflows](https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/triggering-a-workflow#triggering-a-workflow-from-a-workflow).
+- `pat` — uses a Personal Access Token stored as a `COPIER_UPDATE_TOKEN` repository secret. PRs will trigger CI normally.
+
+To enable it on an existing project, run:
+
+```
+copier update --data auto_update=github-token
+```

template/.github/workflows/{% if auto_update != 'none' %}copier-update.yaml{% endif %}.jinja

@@ -0,0 +1,91 @@
+name: Copier Update
+
+on:
+  schedule:
+    - cron: '0 5 * * 1'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  copier-update:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+{%- if auto_update == 'pat' %}
+          token: {% raw %}${{ secrets.COPIER_UPDATE_TOKEN }}{% endraw %}
+{%- endif %}
+          fetch-depth: 0
+
+      - name: Install Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+
+      - name: Install copier
+        run: pip install copier
+
+      - name: Update from template
+        # --trust is required for non-interactive mode; it allows execution of
+        # any _tasks defined by the upstream template.
+        run: copier update --defaults --force --trust
+
+      - name: Check for changes
+        id: check
+        run: |
+          if [ -n "$(git status --porcelain)" ]; then
+            echo "changed=true" >> $GITHUB_OUTPUT
+          else
+            echo "changed=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Check for existing PR
+        if: {% raw %}${{ steps.check.outputs.changed == 'true' }}{% endraw %}
+
+        id: existing-pr
+        env:
+{%- if auto_update == 'pat' %}
+          GH_TOKEN: {% raw %}${{ secrets.COPIER_UPDATE_TOKEN }}{% endraw %}
+{%- else %}
+          GH_TOKEN: {% raw %}${{ github.token }}{% endraw %}
+{%- endif %}
+        run: |
+          EXISTING=$(gh pr list --state open --json headRefName,number --jq '[.[] | select(.headRefName | startswith("copier-update/"))][0].number')
+          if [ -n "$EXISTING" ]; then
+            echo "exists=true" >> $GITHUB_OUTPUT
+            echo "::notice::Update PR #$EXISTING already exists, skipping."
+          else
+            echo "exists=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Create PR
+        if: {% raw %}${{ steps.check.outputs.changed == 'true' && steps.existing-pr.outputs.exists == 'false' }}{% endraw %}
+
+        env:
+{%- if auto_update == 'pat' %}
+          GH_TOKEN: {% raw %}${{ secrets.COPIER_UPDATE_TOKEN }}{% endraw %}
+{%- else %}
+          GH_TOKEN: {% raw %}${{ github.token }}{% endraw %}
+{%- endif %}
+        run: |
+          BRANCH="copier-update/{% raw %}${{ github.run_id }}{% endraw %}"
+          git config user.name "copier-update[bot]"
+          git config user.email "copier-update[bot]@users.noreply.github.com"
+          git checkout -b "$BRANCH"
+          git add .
+          git commit -m "Update from copier template"
+          git push origin "$BRANCH"
+          gh pr create \
+            --title "Update from copier template" \
+            --body "Automated update from the upstream copier template.
+
+          This PR was created by the \`copier-update\` workflow.
+          Please review the changes carefully before merging.
+
+          > If there are conflicts or unexpected changes, you can run
+          > \`copier update\` locally to resolve them interactively."