Create idempotent repository bootstrap workflow for post-template setup

[MariusStorhaug]

Setting up a new module repository using Process-PSModule requires multiple manual steps documented in the README: enabling GitHub Pages, removing branch protection on the github-pages environment, creating a PowerShell Gallery API key, and adding the APIKEY secret. Several open issues (#190, #106, #61, #213, #214, #215, #319) identify additional setup steps that are currently manual.

Request

Current experience

After creating a repository from the Template-PSModule, a maintainer must manually:

1. Navigate to repository settings → Pages → set deployment to "GitHub Actions"
2. Navigate to the github-pages environment → remove branch protection for main
3. Create an API key on PowerShell Gallery with the correct scope
4. Add the APIKEY secret to the repository (or organization)
5. Optionally set repository description, homepage URL, and labels from the module manifest

These steps are error-prone and easily forgotten, leading to failed first publishes and misconfigured repositories.

Desired experience

An idempotent bootstrap workflow (or script) that automates all repository configuration after template instantiation. Running it multiple times produces the same result — it detects current state and only applies changes that are missing.

Acceptance criteria

• GitHub Pages is enabled and configured for GitHub Actions deployment
• The github-pages environment branch protection is configured correctly
• Repository description is set from the module manifest (if present)
• Repository homepage URL is set to the GitHub Pages URL
• Repository labels are standardized (matching the PSModule label set)
• EnforceHttps is enabled on GitHub Pages
• The workflow is idempotent — safe to re-run at any time
• The workflow can be triggered via workflow_dispatch for initial setup and ad-hoc corrections

Note

This aligns with Twelve-Factor App Factor XII (Admin processes): "Run admin/management tasks as one-off processes." Repository bootstrap is a classic admin process that should be codified, not documented as manual steps.

Related issues

• Evaluate automation approaches for post-template GitHub Pages setup #319 — Evaluate automation approaches for post-template GitHub Pages setup
• Set repository homepage to GitHub Pages URL after publishing docs on main #190 — Set repository homepage to GitHub Pages URL after publishing docs on main
• Ensure GitHub Pages is enabled and configured on the repository #106 — Ensure GitHub Pages is enabled and configured on the repository
• Set repository description, labels, and URL from module manifest #61 — Set repository description, labels, and URL from module manifest
• Add test to verify repository homepage matches GitHub Pages URL #213 — Add test to verify repository homepage matches GitHub Pages URL
• Add test to verify GitHub Pages has EnforceHttps enabled #214 — Add test to verify GitHub Pages has EnforceHttps enabled
• Add test to verify repository homepage URL availability #215 — Add test to verify repository homepage URL availability

---

Technical decisions

Approach: Create a new reusable workflow Bootstrap-Repository.yml (or a composite action) that uses the GitHub API to configure repository settings. This workflow runs via workflow_dispatch and can optionally be called from the main workflow.yml on first successful publish.

API endpoints needed:

• PATCH /repos/{owner}/{repo} — set description, homepage, has_pages
• POST /repos/{owner}/{repo}/pages — enable Pages with Actions source
• PUT /repos/{owner}/{repo}/environments/{environment_name} — configure environment protection rules
• GET/PUT /repos/{owner}/{repo}/labels — sync labels

Idempotency: Each step checks current state before mutating. For example, if Pages is already enabled with the correct source, the step is a no-op.

Permissions: The workflow needs administration: write (for Pages/environment config) and contents: read (for reading the manifest). This is a privileged operation, which is appropriate for a one-off admin workflow triggered manually.

Scope of this issue: This issue covers the bootstrap workflow itself. The individual test issues (#213, #214, #215) remain valid as ongoing validation that the configuration has not drifted.

---

Implementation plan

Bootstrap workflow

• Create Bootstrap-Repository.yml with workflow_dispatch trigger
• Implement step to enable GitHub Pages with Actions deployment source
• Implement step to configure github-pages environment protection rules
• Implement step to set repository description from module manifest
• Implement step to set repository homepage to GitHub Pages URL
• Implement step to enable EnforceHttps on GitHub Pages
• Implement step to sync repository labels with the PSModule standard set
• Add idempotency checks to each step (skip if already configured)

Documentation

• Update README "How to get started" to reference the bootstrap workflow
• Simplify manual steps to: create from template → run bootstrap → add API key secret

Testing

• Test on a fresh repository created from Template-PSModule
• Test idempotency by running the workflow twice
• Verify all settings are correctly applied