Merge pull request #399 from dokku/388-exercise-every-documented-task-example-offline-validation-integration

test: exercise every documented task example

Author: josegonzalez

.github/workflows/test.yml

@@ -65,7 +65,48 @@ jobs:
       - name: install dokku maintenance plugin
         run: sudo dokku plugin:install https://github.com/dokku/dokku-maintenance.git maintenance
       - name: run integration tests (shard ${{ matrix.shard }} of 4)
-        run: sudo DOKKU_TEST_SHARD=${{ matrix.shard }} DOKKU_TEST_SHARDS=4 go test -v -count=1 -timeout 20m -run TestIntegration ./tasks/
+        run: sudo DOKKU_TEST_SHARD=${{ matrix.shard }} DOKKU_TEST_SHARDS=4 go test -v -count=1 -timeout 20m -run TestIntegration -skip TestIntegrationTaskExamples ./tasks/
+
+  task-examples-test:
+    name: task-examples-test
+    runs-on: ubuntu-24.04
+    strategy:
+      fail-fast: false
+      matrix:
+        shard: [1, 2, 3, 4]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-go@v7
+        with:
+          go-version-file: go.mod
+      - name: enable docker legacy link support
+        run: |
+          sudo mkdir -p /etc/systemd/system/docker.service.d
+          printf '[Service]\nEnvironment="DOCKER_KEEP_DEPRECATED_LEGACY_LINKS_ENV_VARS=1"\n' | sudo tee /etc/systemd/system/docker.service.d/legacy-links.conf
+          sudo systemctl daemon-reload
+          sudo systemctl restart docker
+      - name: install dokku
+        run: |
+          sudo mkdir -p /etc/apt/keyrings
+          curl -fsSL https://packagecloud.io/dokku/dokku/gpgkey | sudo gpg --dearmor -o /etc/apt/keyrings/dokku-archive-keyring.gpg
+          echo "deb [signed-by=/etc/apt/keyrings/dokku-archive-keyring.gpg] https://packagecloud.io/dokku/dokku/ubuntu/ $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/dokku.list
+          sudo apt-get update -qq
+          sudo DEBIAN_FRONTEND=noninteractive DEBCONF_NONINTERACTIVE_SEEN=true apt-get install -qq -y dokku=0.38.22
+          sudo dokku plugin:install-dependencies --core
+      - name: install dokku redis plugin
+        run: sudo dokku plugin:install https://github.com/dokku/dokku-redis.git redis
+      - name: install dokku http-auth plugin
+        run: sudo dokku plugin:install https://github.com/dokku/dokku-http-auth.git http-auth
+      - name: install dokku global-cert plugin
+        run: sudo dokku plugin:install https://github.com/dokku-community/dokku-global-cert.git global-cert
+      - name: install dokku letsencrypt plugin
+        run: sudo dokku plugin:install https://github.com/dokku/dokku-letsencrypt.git --committish 0.25.0 letsencrypt
+      - name: install dokku acl plugin
+        run: sudo dokku plugin:install https://github.com/dokku-community/dokku-acl.git acl
+      - name: install dokku maintenance plugin
+        run: sudo dokku plugin:install https://github.com/dokku/dokku-maintenance.git maintenance
+      - name: apply documented task examples (shard ${{ matrix.shard }} of 4)
+        run: sudo DOKKU_TEST_SHARD=${{ matrix.shard }} DOKKU_TEST_SHARDS=4 go test -v -count=1 -timeout 30m -run '^TestIntegrationTaskExamples$' ./tasks/
 
   scheduler-k3s-test:
     name: scheduler-k3s-test
@@ -93,6 +134,34 @@ jobs:
         run: sudo dokku scheduler-k3s:initialize --server-ip 127.0.0.1
       - name: run scheduler-k3s integration tests
         run: sudo DOKKU_TEST_SCHEDULER_K3S=1 go test -v -count=1 -timeout 30m -run '^TestIntegrationSchedulerK3s' ./tasks/
+      - name: apply scheduler-k3s documented examples
+        run: sudo DOKKU_TEST_SCHEDULER_K3S=1 go test -v -count=1 -timeout 30m -run '^TestIntegrationTaskExamples/dokku_scheduler_k3s' ./tasks/
+
+  letsencrypt-example-test:
+    name: letsencrypt-example-test
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-go@v7
+        with:
+          go-version-file: go.mod
+      - name: install dokku
+        run: |
+          sudo mkdir -p /etc/apt/keyrings
+          curl -fsSL https://packagecloud.io/dokku/dokku/gpgkey | sudo gpg --dearmor -o /etc/apt/keyrings/dokku-archive-keyring.gpg
+          echo "deb [signed-by=/etc/apt/keyrings/dokku-archive-keyring.gpg] https://packagecloud.io/dokku/dokku/ubuntu/ $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/dokku.list
+          sudo apt-get update -qq
+          sudo DEBIAN_FRONTEND=noninteractive DEBCONF_NONINTERACTIVE_SEEN=true apt-get install -qq -y dokku=0.38.22
+          sudo dokku plugin:install-dependencies --core
+      - name: stand up the pebble ACME server
+        run: |
+          git clone --depth 1 https://github.com/dokku/dokku-letsencrypt.git /tmp/dokku-letsencrypt
+          docker build -t letest-lego:latest /tmp/dokku-letsencrypt/tests/lego
+          mkdir -p /tmp/letest-host
+          LETEST_HOST_DIR=/tmp/letest-host docker compose -f /tmp/dokku-letsencrypt/tests/docker-compose.yml up -d --wait
+          PLUGIN_SRC=/tmp/dokku-letsencrypt bash /tmp/dokku-letsencrypt/tests/setup-native.sh
+      - name: apply the letsencrypt documented example
+        run: sudo DOKKU_TEST_LETSENCRYPT=1 go test -v -count=1 -timeout 20m -run '^TestIntegrationTaskExamples/dokku_letsencrypt$' ./tasks/
 
   bats-test:
     name: bats-test

docs/tasks/dokku_git_from_archive.md

@@ -21,20 +21,21 @@ Supported.
 
 ## Examples
 
-### Deploy a tar archive
+### Deploy a tar.gz archive
 
 ```yaml
 dokku_git_from_archive:
     app: node-js-app
-    archive_url: https://example.com/release-1.0.0.tar
+    archive_url: https://github.com/dokku/smoke-test-app/archive/refs/heads/master.tar.gz
+    archive_type: tar.gz
 ```
 
 ### Deploy a zip archive with author metadata
 
 ```yaml
 dokku_git_from_archive:
     app: node-js-app
-    archive_url: https://example.com/release-1.0.0.zip
+    archive_url: https://github.com/dokku/smoke-test-app/archive/refs/heads/master.zip
     archive_type: zip
     git_username: deploy-bot
     git_email: deploy@example.com

docs/tasks/dokku_git_from_image.md

@@ -26,16 +26,15 @@ Partial - the image reference is written to the companion vars-file.
 ```yaml
 dokku_git_from_image:
     app: node-js-app
-    image: dokku/node-js-app:latest
+    image: dokku/smoke-test-app:dockerfile
 ```
 
-### Deploy from an image with a build directory and git author
+### Deploy from an image with git author metadata
 
 ```yaml
 dokku_git_from_image:
     app: node-js-app
-    image: dokku/node-js-app:latest
-    build_dir: /app
+    image: dokku/smoke-test-app:dockerfile
     git_username: dokku
     git_email: dokku@example.com
 ```

docs/tasks/dokku_git_property.md

@@ -38,12 +38,11 @@ dokku_git_property:
     value: "true"
 ```
 
-### Setting the rev env var globally
+### Setting the rev env var for an app
 
 ```yaml
 dokku_git_property:
-    app: ""
-    global: true
+    app: node-js-app
     property: rev-env-var
     value: GIT_REV
 ```

docs/tasks/dokku_git_sync.md

@@ -41,7 +41,7 @@ dokku_git_sync:
 dokku_git_sync:
     app: hello-world
     remote: https://github.com/dokku/smoke-test-app.git
-    git_ref: main
+    git_ref: master
     build: true
     build_if_changes: false
     skip_deploy_branch: false

docs/tasks/dokku_haproxy_property.md

@@ -20,11 +20,12 @@ Supported.
 
 ## Examples
 
-### Setting the letsencrypt email for an app
+### Setting the letsencrypt email globally
 
 ```yaml
 dokku_haproxy_property:
-    app: node-js-app
+    app: ""
+    global: true
     property: letsencrypt-email
     value: admin@example.com
 ```
@@ -39,11 +40,12 @@ dokku_haproxy_property:
     value: INFO
 ```
 
-### Clearing the letsencrypt email for an app
+### Clearing the letsencrypt email globally
 
 ```yaml
 dokku_haproxy_property:
-    app: node-js-app
+    app: ""
+    global: true
     property: letsencrypt-email
     state: absent
 ```

docs/tasks/dokku_traefik_property.md

@@ -20,11 +20,12 @@ Supported.
 
 ## Examples
 
-### Setting the letsencrypt email for an app
+### Setting the letsencrypt email globally
 
 ```yaml
 dokku_traefik_property:
-    app: node-js-app
+    app: ""
+    global: true
     property: letsencrypt-email
     value: admin@example.com
 ```
@@ -39,11 +40,12 @@ dokku_traefik_property:
     value: INFO
 ```
 
-### Clearing the letsencrypt email for an app
+### Clearing the letsencrypt email globally
 
 ```yaml
 dokku_traefik_property:
-    app: node-js-app
+    app: ""
+    global: true
     property: letsencrypt-email
     state: absent
 ```

docs/writing-tasks.md

@@ -216,6 +216,16 @@ make docs
 This runs `go generate generate/docs.go`, which writes one `docs/tasks/<task>.md` per registered
 task plus the `docs/tasks/README.md` index. Commit the regenerated files alongside your code.
 
+Because the examples are published as-is, they are also tested. `TestAllTaskExamplesValidate`
+(`tasks/main_test.go`) decodes every example offline, applies the field defaults, and runs the
+task's `Validate()`, so a snippet that would fail `docket validate` cannot ship - it runs as part of
+`make test`. `TestIntegrationTaskExamples` (`tasks/example_integration_test.go`) then applies every
+example against a live Dokku under `make test-integration`. Write examples that are actually
+runnable: reference real resources (a reachable image or archive, not a placeholder URL), and if a
+task needs a prerequisite the shared placeholder apps do not provide - a backing service, a deployed
+app, a plugin, a cluster - or its documented value cannot apply verbatim (a secret or inline PEM),
+declare it in the driver's `exampleIntegrationPolicy` rather than leaving the example unapplied.
+
 ## See also
 
 - [Tasks](tasks/README.md) - the generated reference for every task