diff --git a/.gitignore b/.gitignore index 950df6c1..67502dc9 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,5 @@ vendor* -build +build/* dist *.egg-info *.egg @@ -13,6 +13,7 @@ dist .eggs venv* +.venv .act* buildrunner/version.py diff --git a/README.rst b/README.rst index 90647873..f133b96a 100755 --- a/README.rst +++ b/README.rst @@ -1128,6 +1128,11 @@ Common Issues See `docs/common-issues `_. +Example Configurations +====================== + +See `examples `_. + Contributing ============ diff --git a/examples/README.rst b/examples/README.rst new file mode 100644 index 00000000..ae93b32e --- /dev/null +++ b/examples/README.rst @@ -0,0 +1,42 @@ +================================== +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. **Execute Buildrunner with a specified configuration file:** + .. code-block:: sh + + PYTHONPATH=. ./bin/buildrunner -f examples/ + + *Example:* + + .. code-block:: sh + + PYTHONPATH=. ./bin/buildrunner -f examples/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. \ No newline at end of file diff --git a/examples/build/basic/buildrunner.yaml b/examples/build/basic/buildrunner.yaml new file mode 100644 index 00000000..dcaff78f --- /dev/null +++ b/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 diff --git a/examples/run/basic/buildrunner.yaml b/examples/run/basic/buildrunner.yaml new file mode 100644 index 00000000..5c06aae4 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/tests/test_buildrunner_files.py b/tests/test_buildrunner_files.py index 1f028ce4..69965393 100644 --- a/tests/test_buildrunner_files.py +++ b/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)