Add a getting-started page on deploying code with r10k by miharp · Pull Request #510 · OpenVoxProject/openvox-docs

miharp · 2026-10-07T13:22:22Z

Adds a getting-started page, Deploying Code with r10k, between "Setting up a Server" and "Architecture and Concepts" in the ecosystem collection, plus a nav entry and cross-links from the two neighbouring pages.

The trail ended with a control repository and no documented way to get it onto the server. The page covers:

installing r10k with the puppet/r10k module (scratch modulepath and puppet apply for the first run, the control repository afterwards)
a read-only deploy key for root, and the first r10k deploy environment --modules
triggering deploys: cron, then push-triggered deploys with webhook-go via the module's r10k::webhook class
the git-server side for GitHub and GitLab, including the self-managed GitLab rejection of webhooks aimed at private addresses (422 Invalid url given) and the admin setting that allows them
a module-repository hook, a note on the unmaintained abrader-gms git_webhook path, and a short troubleshooting list

Verification

Every command on the page was run as written on a Hetzner lab (OpenVox 8 server on AlmaLinux 10, agents on AlmaLinux 9 and Ubuntu 24.04) against a self-managed GitLab 19.4.1, gitlab.com, and GitHub:

module install into a scratch modulepath, the rendered r10k.yaml, and the gem landing in the agent's Ruby, on the master and on a node with no r10k at all
deploy key flow, first deploy of 15 branches, r10k::webhook with the queue enabled
the 422 reproduced while local requests are blocked, hook creation and GitLab's own test delivery after the setting change, and real push deliveries from all three services answered 202 with r10k runs
GitHub's initial ping answered 500, as the page says
a branch named feature-x deploys as feature_x, which the page now describes

Two findings from the lab went into the page: GitLab caches the outbound-requests setting for about a minute, so pushes right after the change still fail and need resending, and the module links /usr/bin/r10k.

The web-form labels were checked too: GitHub's against the live Settings pages, GitLab's against the form sources in gitlabhq (shared/deploy_keys/_form, admin/application_settings/_outbound, and the webhooks/components Vue files).

Review changes (second commit)

Following the review: r10k, the systemd timer and webhook-go all run as the puppet user (deploy key in its data directory, cachedir under the server vardir, service_user on r10k::webhook); the cron example is now a systemd service and timer; and a new section covers flushing the environment cache from r10k's postrun when environment_timeout is unlimited. OpenVox Server 9 ships the auth.conf rule that allows the flush, and it is backported to the 8.x branch (openvox-server #645) but not in a release yet, so for 8.16.0 and earlier the page shows the rule to add; the stock configuration answers 403. All of it was re-run on the lab from a snapshot: deploys as puppet by hand, by timer and by webhook, the 403 on 8.15.2, and the 204 after adding the rule.

Closes #509

Assisted by Claude.

bastelfreak · 2026-10-07T14:33:51Z

@@ -0,0 +1,320 @@
+---
+layout: default
+title: "Deploying Code with r10k"


In a future PR, would you be interested in documenting codavox here as well? (maybe "Deploying Code with r10k" is a too specific title). We could also mention g10k in another PR here.

Happy to, been meaning to get around to writing a codavox blog post

bastelfreak · 2026-10-07T14:37:27Z

+## Give r10k access to your repository
+
+r10k shells out to `git`, so it uses whatever SSH configuration the user running it has.
+The webhook service and cron both run r10k as `root`, so create a key for `root` and register its public half as a read-only deploy key on the control repository.


IMHO we should change this in the future and run it as puppet. Puppet Enterprise also does it as pe-puppet user. I've this in my provisioning:

# figure out if we're on PE or OpenSource user=$(id pe-puppet &>/dev/null && echo pe-puppet || echo puppet) systemd-run --uid="$user" --gid="$user" --wait /usr/local/bin/r10k deploy environment production --modules --incremental --exclude-spec --verbose

https://github.com/voxpupuli/puppet-r10k/blob/master/manifests/webhook.pp#L21 I have service_user => 'puppet', in my puppet code.

bastelfreak · 2026-10-07T14:46:33Z

+A cron entry that deploys every fifteen minutes is enough for many sites:
+
+```text
+*/15 * * * * root /opt/puppetlabs/puppet/bin/r10k deploy environment --modules


Could you instead recommend a systemd timer?

alaunay · 2026-10-07T16:31:52Z

+
+```console
+sudo ssh-keygen -t ed25519 -N '' -C "r10k@$(hostname -f)" \
+  -f /root/.ssh/id_ed25519


same here with the puppet vs root user

bastelfreak · 2026-10-08T11:51:42Z

+All commands on this page run on the OpenVox server node.
+
+The `puppet-r10k` release used here declares support for OpenVox 8 only.
+On an OpenVox 9 server, check the [module's dependencies](https://forge.puppet.com/modules/puppet/r10k/dependencies) for a release that lists OpenVox 9 before relying on it.


I released a new version of the module. It now lists OpenVox 9.

Covers installing r10k with the puppet-r10k module, giving it a read-only deploy key, the first deploy by hand, cron and webhook-go for automatic deploys, and the GitHub and GitLab hook setup, including the GitLab outbound-requests setting that rejects webhooks on private addresses with "Invalid url given". Every command was run as written on the Hetzner lab against GitLab 19.4.1 (self-managed), gitlab.com and GitHub. Findings folded in: r10k deploys a dashed branch under its corrected name, GitLab caches the outbound-requests setting for about a minute, the module links /usr/bin/r10k, vcsrepo is pinned to the version the Forge resolver picks, and the form labels match GitHub's live settings pages and GitLab's form sources. Closes OpenVoxProject#509 Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Signed-off-by: Michael Harp <mike@mikeharp.com>

…nt cache Addresses bastelfreak's review: r10k, the timer and webhook-go all run as the puppet user (deploy key in its data directory, cachedir under the server vardir, service_user on r10k::webhook), the cron example becomes a systemd service and timer, and a new section covers flushing the environment cache from r10k's postrun when environment_timeout is unlimited. On OpenVox Server 8 that needs the auth.conf rule that 9.x ships; both the 403 and the 204 after adding it were verified on the lab, as were the puppet-user deploys by hand, by timer and by webhook. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Signed-off-by: Michael Harp <mike@mikeharp.com>

…ed yet openvox-server #640 was labelled backport 8.x and #645 merged it into the 8.x branch on 2026-09-17; no 8.x release has shipped since 8.16.0, so the page says 8.16.0 and earlier need the rule added by hand. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Signed-off-by: Michael Harp <mike@mikeharp.com>

puppet-r10k 15.3.0 (2026-10-08) widens the openvox requirement to >= 8.19.0 < 10.0.0, so the tip warning OpenVox 9 users off the module is no longer needed. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Signed-off-by: Michael Harp <mike@mikeharp.com>

miharp force-pushed the docs/r10k-deploy branch from a1a56d2 to c1e34a2 Compare October 7, 2026 13:38

miharp marked this pull request as ready for review October 7, 2026 13:38

miharp requested a review from a team as a code owner October 7, 2026 13:38

miharp force-pushed the docs/r10k-deploy branch from c1e34a2 to 5326776 Compare October 7, 2026 14:09

bastelfreak reviewed Oct 7, 2026

View reviewed changes

alaunay reviewed Oct 7, 2026

View reviewed changes

miharp requested a review from bastelfreak October 8, 2026 10:48

miharp mentioned this pull request Oct 8, 2026

Add release notes for OpenVox 8.30.0, Server 8.17.0, OpenVoxDB 8.17.0, and OpenFact 5.7.x #511

Merged

miharp force-pushed the docs/r10k-deploy branch from b57ee2e to 8b40f68 Compare October 8, 2026 11:48

bastelfreak reviewed Oct 8, 2026

View reviewed changes

miharp and others added 4 commits October 8, 2026 11:49

miharp force-pushed the docs/r10k-deploy branch from 8e16f6e to 36f2f65 Compare October 8, 2026 15:49

Navigation Menu

Repository navigation

Add a getting-started page on deploying code with r10k - #510

Add a getting-started page on deploying code with r10k#510
miharp wants to merge 4 commits into
OpenVoxProject:masterfrom
miharp:docs/r10k-deploy

miharp commented Oct 7, 2026 •

edited

Loading

Uh oh!

bastelfreak Oct 7, 2026 •

edited

Loading

Uh oh!

miharp Oct 7, 2026

Uh oh!

bastelfreak Oct 7, 2026

Uh oh!

bastelfreak Oct 7, 2026

Uh oh!

bastelfreak Oct 7, 2026

Uh oh!

alaunay Oct 7, 2026

Uh oh!

bastelfreak Oct 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

miharp commented Oct 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Verification

Review changes (second commit)

Uh oh!

bastelfreak Oct 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

miharp Oct 7, 2026

Choose a reason for hiding this comment

Uh oh!

bastelfreak Oct 7, 2026

Choose a reason for hiding this comment

Uh oh!

bastelfreak Oct 7, 2026

Choose a reason for hiding this comment

Uh oh!

bastelfreak Oct 7, 2026

Choose a reason for hiding this comment

Uh oh!

alaunay Oct 7, 2026

Choose a reason for hiding this comment

Uh oh!

bastelfreak Oct 8, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

miharp commented Oct 7, 2026 •

edited

Loading

bastelfreak Oct 7, 2026 •

edited

Loading