Merge pull request #4093 from werf/docs-build-container-commit-info

docs(build): expose commit info through env vars in container

docs/pages_en/advanced/building_images_with_stapel/assembly_instructions.md

@@ -312,6 +312,26 @@ src: {{`{{item}}`}}
 - Only raw and command modules support Live stdout output. Other modules display contents of stdout and stderr streams after execution.
 - The `apt` module hangs the build process in some debian and ubuntu versions. The derived images are affected as well ([issue #645](https://github.com/werf/werf/issues/645)).
 
+## Environment variables of build container
+
+You can use service environment variables which are available in build container during the build. They can be used in your shell assembly instructions. Using them will not change the build instructions thus will not trigger stage rebuilds, even when these service environment variables change.
+
+Following environment variables are available:
+- `WERF_COMMIT_HASH`. Example of value: `cda9d17265d174c62424e8f7b5e5640bf749c565`
+- `WERF_COMMIT_TIME_HUMAN`. Example of value: `2022-01-24 17:26:19 +0300 +0300`
+- `WERF_COMMIT_TIME_UNIX`. Example of value: `1643034379`
+
+Usage example:
+{% raw %}
+```yaml
+shell:
+  install:
+  - echo "Commands on the Install stage for $WERF_COMMIT_HASH"
+```
+{% endraw %}
+
+In the example above the hash of the current commit will be added to the `echo ...` command, but this will happen in the very last moment — when the build instructions will be interpreted and executed by the shell. This way there will be no "install" stage rebuilds on every commit.
+
 ## Dependencies of user stages
 
 werf features the ability to define dependencies for rebuilding the _stage_. As described in the [_stages_ reference]({{ "internals/stages_and_storage.html" | true_relative_url }}), _stages_ are built one by one, and the _digest_ is calculated for each _stage_. _Digests_ have various dependencies. When dependencies change, the _stage digest_ changes as well. As a result, werf rebuilds this _stage_ and all the subsequent _stages_.

docs/pages_ru/advanced/building_images_with_stapel/assembly_instructions.md

@@ -339,6 +339,26 @@ src: {{`{{item}}`}}
 - Live-вывод реализован только для модулей `raw` и `command`. Остальные модули отображают вывод каналов `stdout` и `stderr` после выполнения, что приводит к задержкам, скачкообразному выводу.
 - Модуль `apt` подвисает на некоторых версиях Debian и Ubuntu. Проявляется также на наследуемых образах([issue #645](https://github.com/werf/werf/issues/645)).
 
+## Переменные окружения сборочного контейнера
+
+Вы можете использовать сервисные переменные окружения, которые доступны в сборочном контейнере, и, соответственно, доступны в инструкциях сборки. Их использование не приведёт к изменению инструкций сборки и вытекающим из этого пересборкам, даже если сами значения сервисных переменных меняются.
+
+Доступны следующие переменные:
+- `WERF_COMMIT_HASH`. Пример значения: `cda9d17265d174c62424e8f7b5e5640bf749c565`
+- `WERF_COMMIT_TIME_HUMAN`. Пример значения: `2022-01-24 17:26:19 +0300 +0300`
+- `WERF_COMMIT_TIME_UNIX`. Пример значения: `1643034379`
+
+Пример использования:
+{% raw %}
+```yaml
+shell:
+  install:
+  - echo "Commands on the Install stage for $WERF_COMMIT_HASH"
+```
+{% endraw %}
+
+В примере выше хэш текущего коммита будет подставлен в команду `echo ...`, но произойдет это в самый последний момент — на этапе выполнения инструкций shell'ом. Таким образом пересборок слоя install на каждом коммите происходить не будет.
+
 ## Зависимости пользовательских стадий
 
 Одна из особенностей werf — возможность определять зависимости, при которых происходит пересборка _стадии_.