Add Examples

.gitignore

@@ -1,5 +1,5 @@
 vendor*
-build
+build/*
 dist
 *.egg-info
 *.egg
@@ -13,6 +13,7 @@ dist
 
 .eggs
 venv*
+.venv
 .act*
 
 buildrunner/version.py

README.rst

@@ -1128,6 +1128,11 @@ Common Issues
 
 See `docs/common-issues <docs/common-issues.rst>`_.
 
+Example Configurations
+======================
+
+See `examples <examples/README.rst>`_.
+
 Contributing
 ============
 

examples/README.rst

@@ -0,0 +1,52 @@
+==================================
+Buildrunner Example Configurations
+==================================
+
+This directory contains example configuration files for Buildrunner, demonstrating various use cases and best practices. These examples serve as references for users looking to configure and execute Buildrunner effectively.
+
+Running Buildrunner with Example Configuration Files
+====================================================
+
+To run Buildrunner using an example configuration file, follow these steps from the root directory of the Buildrunner repository:
+
+1. **Navigate to the Buildrunner repository directory.**
+
+2. **Install Buildrunner:**
+    .. code-block:: sh
+
+      pip install .
+
+    *Tip: It is recommended to install Buildrunner within a virtual environment to avoid conflicts with system-wide dependencies.*
+
+
+3. **Execute Buildrunner with a specified configuration file:**
+    .. code-block:: sh
+
+        ./bin/buildrunner -f examples/<path-to-config-file>
+        or
+        buildrunner -f examples/<path-to-config-file>
+
+    *Example:*
+
+    .. code-block:: sh
+
+      buildrunner -f examples/configs/build/basic/buildrunner.yaml
+
+Adding a New Example Configuration File
+=======================================
+
+To contribute a new example configuration file, adhere to the following guidelines:
+
+1. **File Location & Naming**
+   - Place the new file in the ``examples/`` directory.
+   - Ensure the filename ends with ``.buildrunner.yaml`` to allow automatic detection and execution by unit tests.
+
+2. **Configuration Validity**
+   - The configuration file must contain a valid Buildrunner configuration.
+   - It should execute successfully using the standard instructions provided in this repository without requiring any manual intervention.
+
+3. **Documentation & Additional Files**
+   - If necessary, include a ``README.rst`` file in the same directory as the configuration file to provide additional details or instructions.
+   - Any supporting files required for the configuration should be placed alongside the configuration file.
+
+Following these best practices ensures consistency, maintainability, and ease of use for all contributors and users.

examples/build/basic/buildrunner.yaml

@@ -0,0 +1,7 @@
+# Basic buildrunner configuration to build a simple Docker image.
+steps:
+  simple-build-step:
+    build:
+      dockerfile: |
+        FROM busybox:latest
+        RUN echo Hello World

examples/run/basic/buildrunner.yaml

@@ -0,0 +1,6 @@
+# Basic buildrunner configuration to run a simple Docker image.
+steps:
+  simple-run-step:
+    run:
+      image: busybox:latest
+      cmd: echo Hello World

tests/test_buildrunner_files.py

@@ -117,6 +117,21 @@ def _get_test_runs(
     ]
 
 
+def _get_example_runs(test_dir: str) -> List[Tuple[str, str, Optional[List[str]], int]]:
+    file_names = []
+    # Walk through the examples directory and find all files ending with buildrunner.yaml
+    for root, _, files in os.walk(test_dir):
+        for file in files:
+            file_name = os.path.join(root, file)
+            if file_name.endswith("buildrunner.yaml"):
+                file_names.append(file_name)
+
+    return [
+        (test_dir, file_name, _get_test_args(file_name), _get_exit_code(file_name))
+        for file_name in file_names
+    ]
+
+
 def _test_buildrunner_file(test_dir, file_name, args, exit_code):
     print(f"\n>>>> Testing Buildrunner file: {file_name}")
     with tempfile.TemporaryDirectory(prefix="buildrunner.results-") as temp_dir:
@@ -194,3 +209,11 @@ def test_buildrunner_arm_dir(test_dir: str, file_name, args, exit_code):
 def test_buildrunner_scan_dir(test_dir: str, file_name, args, exit_code):
     # The scan tests can be flaky, with errors like "TOOMANYREQUESTS: retry-after: 804.543µs, allowed: 44000/minute"
     _test_buildrunner_file(test_dir, file_name, args, exit_code)
+
+
+@pytest.mark.parametrize(
+    "test_dir, file_name, args, exit_code",
+    _get_example_runs(test_dir=f"{TEST_DIR}/../examples"),
+)
+def test_example_configs(test_dir: str, file_name, args, exit_code):
+    _test_buildrunner_file(test_dir, file_name, args, exit_code)