From c997b940cb1b5b99adce7cd9d93c6d518e093605 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Antoine=20Beaupr=C3=A9?= <anarcat@debian.org>
Date: Tue, 4 Feb 2025 13:44:46 -0500
Subject: [PATCH] puppet: mention the `--environment` flag

Closes: tpo/tpa/puppet-hiera-enc#1
---
 howto/puppet.md | 31 ++++++++++++++++++++++++-------
 1 file changed, 24 insertions(+), 7 deletions(-)

diff --git a/howto/puppet.md b/howto/puppet.md
index 3a3ec4e1..5623793b 100644
--- a/howto/puppet.md
+++ b/howto/puppet.md
@@ -141,13 +141,30 @@ affects a lot of machines.
 During ordinary maintenance operations, it's appropriate to work directly on the
 default `main` branch, which deploys to the `production` environment.
 
-However, for changesets that are more complex, such as when deploying a new
-service or adding a module (see below), it's recommended to start by working on
-a feature branch which will deploy as a distinct [environment](#environments)
-on the puppet server. By assigning a node to the test environment via the
-[external node classifier](#external-node-classifier-enc), a single node (or a
-small set) can be made to apply test puppet code. Once the feature branch is
-satisfying, it can be then simply merged to `main` and deleted.
+However, for more complex changes, such as when deploying a new
+service or adding a module (see below), it's recommended to start by
+working on a feature branch which will deploy as a distinct
+[environment](#environments) on the Puppet server.
+
+To quickly test a different environment used, you can switch the
+environment used by the Puppet agent using the `--environment`
+flag. For example, this will switch a node from `production` to
+`test`:
+
+    puppet agent --test --environment test
+
+A node or group of nodes can be switch to a different environment
+using the [external node classifier](#external-node-classifier-enc).
+
+Once the feature branch is satisfactory, it can then be merged to
+`main` and deleted:
+
+    git merge test
+    git branch -d test
+    git push -d origin test
+
+Branches are not deleted automatically after merge: make sure you
+cleanup after yourself.
 
 Because environments aren't totally isolated from each other and a compromised
 node could choose to apply an environment other than `production`, care should
-- 
GitLab