Split remote execution into multiple assemblies by aneta-petrova · Pull Request #4753 · theforeman/foreman-documentation

aneta-petrova · 2026-04-02T18:44:05Z

What changes are you introducing?

Creating sub-assemblies in the existing remote execution assembly. The new assemblies are based on 'feature lifecycle phases': overview/learning, getting started, configuring, customizing, reference.

Why are you introducing these changes? (Explanation, links to references, issues, etc.)

The existing assembly is very large (about 30 sections). Splitting it into multiple assemblies helps with navigation.

Part of the CQA (Content Quality Assessment) checklist: One user story per assembly

Anything else to add? (Considerations, potential downsides, alternative solutions you have explored, etc.)

Contributor checklists

I am okay with my commits getting squashed when you merge this PR.
I am familiar with the contributing guidelines.

Please cherry-pick my commits into:

Foreman 3.18/Katello 4.20 (Satellite 6.19)
Foreman 3.17/Katello 4.19
Foreman 3.16/Katello 4.18 (Satellite 6.18; orcharhino 7.6 and 7.7)
Foreman 3.15/Katello 4.17
Foreman 3.14/Katello 4.16 (Satellite 6.17; orcharhino 7.4; orcharhino 7.5)
Foreman 3.13/Katello 4.15 (EL9 only)
Foreman 3.12/Katello 4.14 (Satellite 6.16; orcharhino 7.2 on EL9 only; orcharhino 7.3)
We do not accept PRs for Foreman older than 3.12.

Reorganize remote execution assembly into logical sections Split the remote execution assembly into three focused assemblies to improve navigation and maintainability: - Overview: what REX is, architecture, transport mode comparison - Configuration: setting up hosts, permissions, SSH/Kerberos, templates, running jobs - Reference: advanced settings, cron lines, rate limits Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> Restructure remote execution into five focused assemblies Replace the previous three-section structure with five assemblies following a progressive learning path: - Discovering remote execution: overview, architecture, transport modes - Getting started with remote execution: installation, permissions, first jobs - Configuring remote execution: SmartProxy settings, authentication, SSH/Kerberos - Extending remote execution: job templates, Ansible playbooks, scheduling - Remote execution reference: advanced settings, cron syntax, performance Use gerund-based naming (discovering, getting started, configuring, extending) for better consistency with documentation conventions. Drop _{context} suffix from assembly IDs for cleaner cross-references. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> Fix up assembly introductions Rework remote execution reference

github-actions · 2026-04-02T18:48:25Z

The PR preview for 53e7c86 is available at theforeman-foreman-documentation-preview-pr-4753.surge.sh

The following output files are affected by this PR:

show diff

show diff as HTML

guides/common/modules/con_getting-started-with-remote-execution.adoc

guides/common/modules/con_remote-execution-overview.adoc

Lennonka

Love it!

I've taken a look at the new TOC and the following things jumped out at me.
The rest looks good architecture wise.

guides/common/assembly_getting-started-with-remote-execution.adoc

guides/common/assembly_configuring-remote-execution.adoc

Lennonka · 2026-04-02T19:55:54Z

Btw, I've been thinking about moving Ansible playbook import (example) into the Ansible guide solely because it fits better with the Ansible content journey rather than the REX content journey IMO. But we can do that in another PR ofc if we agree on it.

Lennonka · 2026-04-02T20:03:30Z

guides/common/assembly_remote-execution-overview.adoc

+
+include::modules/con_remote-execution-in-project.adoc[leveloffset=+1]
+
+include::modules/con_remote-execution-workflow.adoc[leveloffset=+1]


Can we reserve the term "workflow" for user workflows and call this a "process"?

I like this question. I do not have an answer/+1/-1.

I think I know what you mean with 'workflow' but also don't think 'process' would be right here. Is it okay if I leave this as is? This is not something I'm changing in this PR, the heading already exists.

Sure, it's okay.

Lennonka · 2026-04-02T20:04:19Z

Feel free to leave changes in headings/titles for another PR. :)

Co-authored-by: Brian Angelica <91690569+bangelic@users.noreply.github.com>

Co-authored-by: Lena Ansorgová <zuansorg@redhat.com>

maximiliankolb

One suggestion about deeply nested assemblies. Overall, I like this PR.

guides/common/modules/con_remote-execution-overview.adoc

maximiliankolb · 2026-04-07T11:39:44Z

guides/common/assembly_remote-execution-overview.adoc

+
+include::modules/con_remote-execution-in-project.adoc[leveloffset=+1]
+
+include::modules/con_remote-execution-workflow.adoc[leveloffset=+1]


I like this question. I do not have an answer/+1/-1.

guides/common/assembly_configuring-remote-execution.adoc

Co-authored-by: Maximilian Kolb <mail@maximilian-kolb.de>

Separate authentication and advanced config assemblies Create reference assembly for remote execution Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

aneta-petrova · 2026-04-07T21:12:23Z

Btw, I've been thinking about moving Ansible playbook import (example) into the Ansible guide solely because it fits better with the Ansible content journey rather than the REX content journey IMO. But we can do that in another PR ofc if we agree on it.

Why not try it if it makes sense, but a separate PR would be better for that with its own round of reviews and all that :)

aneta-petrova · 2026-04-07T21:19:22Z

Thanks for all the brilliant suggestions, this was a very productive peer review. Can I please get a re-review?

Lennonka

LGTM!
Just a few notes, mostly non-blocking.

A second ack by @maximiliankolb would be appreciated.

guides/common/modules/con_remote-execution-overview.adoc

guides/common/modules/con_remote-execution-reference.adoc

maximiliankolb

Thanks Anet, LGTM.

RE Lena's comment: I lean towards applying it.

Co-authored-by: Lena Ansorgová <zuansorg@redhat.com>

--------- Co-authored-by: Brian Angelica <91690569+bangelic@users.noreply.github.com> Co-authored-by: Lena Ansorgová <zuansorg@redhat.com> Co-authored-by: Maximilian Kolb <mail@maximilian-kolb.de> Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com> (cherry picked from commit 593c49d) (cherry picked from commit 331257a)

--------- Co-authored-by: Brian Angelica <91690569+bangelic@users.noreply.github.com> Co-authored-by: Lena Ansorgová <zuansorg@redhat.com> Co-authored-by: Maximilian Kolb <mail@maximilian-kolb.de> Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com> (cherry picked from commit 593c49d)

aneta-petrova · 2026-04-08T10:04:31Z

Merged to "master" and cherry-picked:

20aefbf..a24c485 3.18 -> 3.18
b95a6e4..331257a 3.17 -> 3.17 (a conflict due to the rex SSH certs feature being missing)
8bb602b..9979d27 3.16 -> 3.16 (picked from 3.17)

aneta-petrova added this to the Prepare for DITA migration (RH) milestone Apr 2, 2026

pr-processor bot added the Not yet reviewed label Apr 2, 2026

github-actions bot added Needs tech review Requires a review from the technical perspective Needs style review Requires a review from docs style/grammar perspective Needs testing Requires functional testing labels Apr 2, 2026

bangelic reviewed Apr 2, 2026

View reviewed changes

guides/common/modules/con_getting-started-with-remote-execution.adoc Outdated Show resolved Hide resolved

guides/common/modules/con_remote-execution-overview.adoc Outdated Show resolved Hide resolved

pr-processor bot removed the Not yet reviewed label Apr 2, 2026

Lennonka requested changes Apr 2, 2026

View reviewed changes

guides/common/assembly_getting-started-with-remote-execution.adoc Outdated Show resolved Hide resolved

guides/common/assembly_configuring-remote-execution.adoc Outdated Show resolved Hide resolved

pr-processor bot added the Waiting on contributor Requires an action from the author label Apr 2, 2026

Lennonka reviewed Apr 2, 2026

View reviewed changes

Apply suggestions from style review

0904dbb

Co-authored-by: Brian Angelica <91690569+bangelic@users.noreply.github.com>

pr-processor bot added Needs re-review and removed Waiting on contributor Requires an action from the author labels Apr 7, 2026

Apply suggestions from code review

cd59a8b

Co-authored-by: Lena Ansorgová <zuansorg@redhat.com>

maximiliankolb self-requested a review April 7, 2026 10:47

maximiliankolb reviewed Apr 7, 2026

View reviewed changes

pr-processor bot removed the Needs re-review label Apr 7, 2026

aneta-petrova and others added 2 commits April 7, 2026 21:08

Apply suggestion from @maximiliankolb

bc7ca7b

Co-authored-by: Maximilian Kolb <mail@maximilian-kolb.de>

Change cron line syntax module's type

7bde896

aneta-petrova force-pushed the cqa-rex branch from dd6a3d1 to 7bde896 Compare April 7, 2026 20:16

Apply feedback for additional assemblies

207eff3

Separate authentication and advanced config assemblies Create reference assembly for remote execution Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

aneta-petrova force-pushed the cqa-rex branch from c56537c to 207eff3 Compare April 7, 2026 21:06

Fix Vale error

94c6c0e

aneta-petrova removed the Needs tech review Requires a review from the technical perspective label Apr 8, 2026

aneta-petrova removed the Needs testing Requires functional testing label Apr 8, 2026

maximiliankolb self-requested a review April 8, 2026 08:35

Lennonka approved these changes Apr 8, 2026

View reviewed changes

guides/common/modules/con_remote-execution-overview.adoc Outdated Show resolved Hide resolved

guides/common/modules/con_remote-execution-reference.adoc Show resolved Hide resolved

maximiliankolb approved these changes Apr 8, 2026

View reviewed changes

maximiliankolb added style review done No issues from docs style/grammar perspective and removed Needs style review Requires a review from docs style/grammar perspective labels Apr 8, 2026

Apply suggestion from @Lennonka

53e7c86

Co-authored-by: Lena Ansorgová <zuansorg@redhat.com>

maximiliankolb approved these changes Apr 8, 2026

View reviewed changes

aneta-petrova merged commit 593c49d into theforeman:master Apr 8, 2026
10 of 11 checks passed

aneta-petrova deleted the cqa-rex branch April 8, 2026 09:52


		include::modules/con_remote-execution-in-project.adoc[leveloffset=+1]

		include::modules/con_remote-execution-workflow.adoc[leveloffset=+1]

Conversation

aneta-petrova commented Apr 2, 2026

What changes are you introducing?

Why are you introducing these changes? (Explanation, links to references, issues, etc.)

Anything else to add? (Considerations, potential downsides, alternative solutions you have explored, etc.)

Contributor checklists

Uh oh!

github-actions bot commented Apr 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Lennonka left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Lennonka commented Apr 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Lennonka Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

maximiliankolb Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

aneta-petrova Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

Lennonka Apr 8, 2026

Choose a reason for hiding this comment

Uh oh!

Lennonka commented Apr 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

maximiliankolb left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

maximiliankolb Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

aneta-petrova commented Apr 7, 2026

Uh oh!

aneta-petrova commented Apr 7, 2026

Uh oh!

Lennonka left a comment • 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!

Uh oh!

Uh oh!

maximiliankolb left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

aneta-petrova commented Apr 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

github-actions bot commented Apr 2, 2026 •

edited

Loading

Lennonka commented Apr 2, 2026 •

edited

Loading

Lennonka commented Apr 2, 2026 •

edited

Loading

Lennonka left a comment •

edited

Loading