Repomatic setup guide

[kdeldycke]

✅ Create and configure the token

Some workflows need a fine-grained personal access token to create PRs that update files in .github/workflows/. Without it, those jobs will silently fail.

1. Open the pre-filled token form (or go to GitHub → Settings → Developer Settings → Fine-grained tokens and click Generate new token).

2. Review the pre-filled Token name (repomatic-repomatic).

3. Under Repository access, select Only select repositories and pick repomatic. Do not grant access to other repositories.

4. Verify these permissions (pre-filled by the link above):

   Permission	Access	Reason
   Commit statuses	Read and Write	Renovate stability-days status checks
   Contents	Read and Write	Tag pushes, release publishing, PR branch creation
   Dependabot alerts	Read-only	Renovate reads vulnerability alerts to create security PRs
   Issues	Read and Write	Renovate Dependency Dashboard
   Metadata	Read-only (mandatory)	Required for all fine-grained token API operations
   Pull requests	Read and Write	All PR-creating jobs (sync-repomatic, fix-typos, prepare-release, Renovate)
   Workflows	Read and Write	Push changes to .github/workflows/ files — not available via YAML permissions: at all

5. Click Generate token and copy it.

[!TIP]
Token expiration: Fine-grained PATs expire. Set a calendar reminder to rotate the token, or workflows will fail silently.

Run this command and paste the token when prompted:

gh secret set REPOMATIC_PAT --repo kdeldycke/repomatic

Or add it manually: this repo → Settings → Secrets → Actions → New repository secret → name it REPOMATIC_PAT → paste the token.

✅ Configure Dependabot settings

Enable vulnerability alerts (Renovate reads these via API) and disable automated security fixes (Renovate handles security PRs):

gh api repos/kdeldycke/repomatic/vulnerability-alerts --method PUT
gh api repos/kdeldycke/repomatic/automated-security-fixes --method DELETE

Disabling security updates also disables grouped security updates. Dependabot version updates and grouped security updates have no API — if either was manually enabled, disable them at this repo → Settings → Advanced Security → Dependabot. (If .github/dependabot.yml exists, the renovate.yaml workflow will remove it automatically.)

ℹ️ Enable immutable releases

Go to this repo → Settings → General, scroll to the Releases section, and enable Release immutability.

This locks git tags and release assets after publication, preventing tampering. Release notes remain editable.

✅ Protect the main branch

Create a branch ruleset to prevent accidental force-pushes or deletions:

1. Ruleset name: main
2. Enforcement status: Active
3. Under Target branches, click Add target → Include default branch
4. Check Restrict deletions and Block force pushes (both are on by default for new rulesets)
5. Click Create

No status checks are required — the above is enough to protect commit history.

[!NOTE]
GitHub prompts repository admins to protect their default branch when none is set. This step silences that prompt and guards against irreversible mistakes.

❌ Register the PyPI Trusted Publisher entry

Register a Trusted Publisher entry on PyPI so the publish-pypi job can upload releases via OIDC, with no long-lived API token.

The publisher matches the OIDC job_workflow_ref claim, which names the caller's workflow file (.github/workflows/release.yaml in this repo). Without a matching entry, the first upload after migration fails with a publisher-mismatch error.

Open the pre-filled Trusted Publishers settings page: the GitHub tab is already selected and every required field is populated. Review the values and click Add:

Field	Value
PyPI Project Name	repomatic
Owner	kdeldycke
Repository name	repomatic
Workflow name	release.yaml
Environment name	(leave blank)

[!NOTE]
The workflow name must be release.yaml, not the upstream reusable workflow path. The composite action invoked from release.yaml inherits the caller's OIDC context, so the claim resolves to this repo's own file. Registering the upstream path triggers pypi/warehouse#11096 on first publish.

If the project does not yet exist on PyPI, register a pending publisher instead from the account-level settings using the same field values. PyPI promotes it to a regular publisher on the first successful upload.

See the PyPI Trusted Publishers documentation for the full registration walkthrough.

✅ Set GitHub Pages deployment source to GitHub Actions

Set the GitHub Pages deployment source to GitHub Actions so the docs.yaml workflow can deploy via actions/deploy-pages.

The fastest fix is a single gh command. Use POST to enable Pages for the first time, or PUT if Pages is already configured with a different source:

# Enable Pages (first time):
gh api --method POST repos/kdeldycke/repomatic/pages -f build_type=workflow

# Or update an existing Pages configuration:
gh api --method PUT repos/kdeldycke/repomatic/pages -f build_type=workflow

Or set it manually at Settings → Pages → Build and deployment → Source → select GitHub Actions.

If the repository has a leftover gh-pages branch from a previous deployment method, delete it after switching:

gh api --method DELETE repos/kdeldycke/repomatic/git/refs/heads/gh-pages

The lint-repo job warns about stale gh-pages branches.

✅ Configure VirusTotal scanning (optional)

Release binaries compiled with Nuitka often trigger false positives on VirusTotal. Submitting binaries proactively on each release seeds AV vendor databases and reduces detection counts for downstream distributors (Chocolatey, Scoop, etc.).

1. Go to VirusTotal and sign in (a free account is sufficient).

2. Copy your API key from the account page.

3. Add it as a repository secret:

gh secret set VIRUSTOTAL_API_KEY --repo kdeldycke/repomatic

Or add it manually: this repo → Settings → Secrets → Actions → New repository secret → name it VIRUSTOTAL_API_KEY → paste the key.

[!NOTE]
This step is optional. Without the key, release workflows skip the VirusTotal scan. The free-tier API allows 4 requests per minute, which is sufficient for typical release binaries.

❌ Verify the setup

Trigger a workflow re-run:

gh workflow run autofix.yaml --repo kdeldycke/repomatic

Or re-run from the Actions tab. Jobs should now update .github/workflows/ files without errors.

This issue will close automatically once all setup steps are verified. Repository state and configuration are continuously checked and enforced by the lint-repo job.

---

🏭 Generated with repomatic 6.18.3.dev0

[kdeldycke]

PAT configured, all permissions verified, repository settings complete.

Workflow metadata

Field	Value
Trigger	push
Actor	@kdeldycke
Ref	main
Commit	55c4be07
Job	setup-guide
Workflow	autofix.yaml
Run	#4252.1

---

🏭 Generated with repomatic 6.11.0.dev0

[kdeldycke]

Condition recurred.

Workflow metadata

Field	Value
Trigger	push
Actor	@kdeldycke
Ref	main
Commit	0a14561d
Job	setup-guide
Workflow	autofix.yaml
Run	#4373.1

---

🏭 Generated with repomatic 6.13.1.dev0

[kdeldycke]

PAT configured, all permissions verified, repository settings complete.

Workflow metadata

Field	Value
Trigger	push
Actor	@kdeldycke
Ref	main
Commit	f1c262c2
Job	setup-guide
Workflow	autofix.yaml
Run	#4375.1

---

🏭 Generated with repomatic 6.13.1.dev0

[kdeldycke]

Condition recurred.

Workflow metadata

Field	Value
Trigger	push
Actor	@kdeldycke
Ref	main
Commit	7d7b5148
Job	setup-guide
Workflow	autofix.yaml
Run	#4538.1

---

🏭 Generated with repomatic 6.17.1.dev0