feature(template): bootstrap new repositories from GitHub metadata

Author: sbgaia

.github/workflows/bootstrap-template.yaml

@@ -0,0 +1,37 @@
+name: Bootstrap Template
+
+on:
+  push:
+
+permissions:
+  contents: write
+
+jobs:
+  bootstrap:
+    if: github.actor != 'github-actions[bot]'
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v5
+      with:
+        fetch-depth: 0
+    - name: Set up Python
+      uses: actions/setup-python@v6
+      with:
+        python-version: '3.13'
+    - name: Bootstrap repository metadata
+      run: python scripts/bootstrap_template.py --from-github
+      env:
+        GITHUB_REPOSITORY: ${{ github.repository }}
+        GITHUB_REPOSITORY_OWNER: ${{ github.repository_owner }}
+        GITHUB_ACTOR: ${{ github.actor }}
+        GITHUB_ACTOR_ID: ${{ github.actor_id }}
+    - name: Commit bootstrap changes
+      run: |
+        if git diff --quiet; then
+          exit 0
+        fi
+        git config user.name "github-actions[bot]"
+        git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+        git add .
+        git commit -m "chore(template): bootstrap repository metadata"
+        git push

README.md

@@ -12,6 +12,13 @@ python scripts/bootstrap_template.py your-repository-name
 
 This renames the placeholder package directory, updates the package metadata, and rewrites the main `project_name` and `python-template` references across the repository. Use `--package-name`, `--project-title`, `--author`, `--author-email`, or `--description` if the defaults inferred from the repository name are not enough.
 
+When the repository is created on GitHub from `Use this template`, the
+`Bootstrap Template` workflow also runs automatically on the first push and
+uses GitHub metadata to rename the repository placeholders. It derives the
+repository name from `github.repository`, the author from
+`github.repository_owner`, and the author email from the GitHub noreply
+address for the triggering actor.
+
 ## Getting started
 
 - <code>Use this template > Create a new repository</code> : You can clone this template from the UI by clicking on the upper left repository button.

scripts/bootstrap_template.py

@@ -4,6 +4,7 @@
 from __future__ import annotations
 
 import argparse
+import os
 import re
 from pathlib import Path
 
@@ -38,8 +39,10 @@ def parse_args() -> argparse.Namespace:
     parser.add_argument(
         "repository_name",
         nargs="?",
-        default=Path.cwd().name,
-        help="Repository/distribution name, defaults to the current directory.",
+        help=(
+            "Repository/distribution name. Defaults to GitHub metadata "
+            "or the current directory."
+        ),
     )
     parser.add_argument(
         "--package-name",
@@ -70,6 +73,14 @@ def parse_args() -> argparse.Namespace:
         default=PLACEHOLDER_DESCRIPTION,
         help="Package description to write into project metadata.",
     )
+    parser.add_argument(
+        "--from-github",
+        action="store_true",
+        help=(
+            "Infer repository metadata from GitHub Actions environment "
+            "variables."
+        ),
+    )
     parser.add_argument(
         "--dry-run",
         action="store_true",
@@ -78,6 +89,51 @@ def parse_args() -> argparse.Namespace:
     return parser.parse_args()
 
 
+def github_noreply_email() -> str:
+    """Build a GitHub noreply email address from available environment data."""
+    actor = os.environ.get("GITHUB_ACTOR", "").strip()
+    actor_id = os.environ.get("GITHUB_ACTOR_ID", "").strip()
+    if actor and actor_id:
+        return f"{actor_id}+{actor}@users.noreply.github.com"
+    if actor:
+        return f"{actor}@users.noreply.github.com"
+    return PLACEHOLDER_AUTHOR_EMAIL
+
+
+def resolve_metadata(args: argparse.Namespace) -> dict[str, str]:
+    """Resolve bootstrap metadata from args and GitHub context."""
+    repository_name = (
+        args.repository_name or os.environ.get("GITHUB_REPOSITORY", "")
+    ).strip()
+    if "/" in repository_name:
+        repository_name = repository_name.rsplit("/", maxsplit=1)[-1]
+    if not repository_name:
+        repository_name = Path.cwd().name
+
+    package_name = (
+        args.package_name or repository_name.replace("-", "_")
+    ).strip()
+    project_title = (
+        args.project_title
+        or repository_name.replace("-", " ").replace("_", " ").title()
+    ).strip()
+
+    author = args.author
+    author_email = args.author_email
+    if args.from_github:
+        author = os.environ.get("GITHUB_REPOSITORY_OWNER", "").strip() or author
+        author_email = github_noreply_email()
+
+    return {
+        "repository_name": repository_name,
+        "package_name": package_name,
+        "project_title": project_title,
+        "author": author,
+        "author_email": author_email,
+        "description": args.description,
+    }
+
+
 def replace_text(
     path: Path,
     replacements: dict[str, str],
@@ -205,14 +261,10 @@ def rename_package_dir(package_name: str, *, dry_run: bool) -> None:
 def main() -> int:
     """Run the template bootstrap process."""
     args = parse_args()
-    repository_name = args.repository_name.strip()
-    package_name = (
-        args.package_name or repository_name.replace("-", "_")
-    ).strip()
-    project_title = (
-        args.project_title
-        or repository_name.replace("-", " ").replace("_", " ").title()
-    ).strip()
+    metadata = resolve_metadata(args)
+    repository_name = metadata["repository_name"]
+    package_name = metadata["package_name"]
+    project_title = metadata["project_title"]
 
     if not repository_name:
         raise ValueError("repository_name must not be empty.")
@@ -255,9 +307,9 @@ def main() -> int:
         Path("pyproject.toml"),
         repository_name=repository_name,
         package_name=package_name,
-        author=args.author,
-        author_email=args.author_email,
-        description=args.description,
+        author=metadata["author"],
+        author_email=metadata["author_email"],
+        description=metadata["description"],
         dry_run=args.dry_run,
     )
     rename_package_dir(package_name, dry_run=args.dry_run)

tests/test_bootstrap_template.py

@@ -171,3 +171,71 @@ def test_bootstrap_template_uses_custom_package_name(tmp_path: Path) -> None:
     assert "::: custom_pkg" in (repo_dir / "docs" / "api.md").read_text(
         encoding="utf-8"
     )
+
+
+def test_bootstrap_template_uses_github_metadata(tmp_path: Path) -> None:
+    repo_dir = tmp_path / "placeholder"
+    repo_dir.mkdir()
+    (repo_dir / ".devcontainer").mkdir()
+    (repo_dir / "docs").mkdir()
+    (repo_dir / "project_name").mkdir()
+
+    (repo_dir / ".devcontainer" / "devcontainer.json").write_text(
+        '{"workspaceFolder": "/workspaces/python-template"}\n',
+        encoding="utf-8",
+    )
+    (repo_dir / "README.md").write_text("# Python Template\n", encoding="utf-8")
+    (repo_dir / "docs" / "index.md").write_text(
+        "# project_name\n", encoding="utf-8"
+    )
+    (repo_dir / "docs" / "api.md").write_text(
+        "::: project_name\n", encoding="utf-8"
+    )
+    (repo_dir / "mkdocs.yml").write_text(
+        "site_name: project_name\nrepo_name: python-template\n",
+        encoding="utf-8",
+    )
+    (repo_dir / "pyproject.toml").write_text(
+        "[project]\n"
+        'name = "project_name"\n'
+        'description = "A simple template project."\n'
+        'authors = [{ name = "Mario Potato", '
+        'email = "mario.potato@univr.it" }]\n'
+        "\n"
+        "[tool.ruff.lint.isort]\n"
+        'known-first-party = ["project_name"]\n',
+        encoding="utf-8",
+    )
+
+    env = {
+        "GITHUB_REPOSITORY": "octo-org/demo-service",
+        "GITHUB_REPOSITORY_OWNER": "octo-org",
+        "GITHUB_ACTOR": "octocat",
+        "GITHUB_ACTOR_ID": "12345",
+    }
+
+    subprocess.run(
+        [
+            sys.executable,
+            str(
+                Path(
+                    "/home/sebastiano/python-template/scripts/bootstrap_template.py"
+                )
+            ),
+            "--from-github",
+        ],
+        cwd=repo_dir,
+        check=True,
+        env=env,
+    )
+
+    assert (repo_dir / "demo_service").exists()
+    assert 'name = "demo-service"' in (repo_dir / "pyproject.toml").read_text(
+        encoding="utf-8"
+    )
+    assert 'name = "octo-org"' in (repo_dir / "pyproject.toml").read_text(
+        encoding="utf-8"
+    )
+    assert "12345+octocat@users.noreply.github.com" in (
+        repo_dir / "pyproject.toml"
+    ).read_text(encoding="utf-8")