working-directory
Тема дорожной карты · GitHub Actions
Ключ working-directory в GitHub Actions позволяет задать директорию, в которой будет выполняться shell-шаг, переопределяя корневую директорию чекаута runner'а по умолчанию для данного run:-блока. Этот ключ особенно полезен при работе с монорепозиториями, поскольку позволяет выполнять команды внутри подпапок, не добавляя команды cd в каждый скрипт. Например, установка working-directory: packages/api позволяет выполнить команды внутри подпапки packages/api, что упрощает управление проектом.
Использование working-directory также позволяет сохранить шаги короткими и читаемыми, что улучшает поддержку и масштабируемость проекта. Кроме того, ключ working-directory может быть закреплен для всего задания через defaults.run.working-directory, что обеспечивает единообразие и упрощает настройку рабочего процесса.
Как это работает
working-directory влияет только на shell-шаги, а не на actions, использующие uses:. Это означает, что каждый action самостоятельно управляет точкой входа в файловую систему. Например, uses: actions/checkout@v4 (клонирование репозитория), uses: actions/setup-node@v4 (установка toolchain для Node.js), uses: setup-python@v5 (установка toolchain для Python), и другие подобные actions. Shell-команды, такие как run: echo "Hello, World!", выполняются в указанной директории.
Для выполнения multi-line скриптов используется синтаксис run: |, который позволяет ввести несколько строк команд. Передача состояния между шагами осуществляется через переменные окружения, такие как $GITHUB_ENV, которые могут использоваться для передачи значений следующим шагам в рамках одного задания.
Условное выполнение шагов можно настроить через ключ if:, что позволяет выполнять определенные шаги только при выполнении определенных условий.
Когда применять
working-directory особенно полезен при работе с монорепозиториями, где команды часто выполняются внутри подпапок. Всегда начинайте с actions/checkout@v4, чтобы получить доступ к исходному коду проекта. Для установки toolchain используйте соответствующие actions, такие как actions/setup-node@v4, setup-python@v5, и другие.
Используйте actions/cache для кеширования зависимостей, чтобы ускорить выполнение шагов. Например, кеширование директорий ~/.npm, ~/.cargo, ~/.gradle, и ~/.m2 может значительно ускорить выполнение шагов, связанных с установкой и использованием зависимостей.
Типичные ошибки
Одной из распространенных ошибок при использовании working-directory является пропуск установки ключа fetch-depth: 0, что может привести к проблемам при выполнении команд, требующих полной истории коммитов, таких как git blame, git log, и git tag. Другой распространенной ошибкой является выполнение дорогостоящих шагов безусловно, что может привести к неоправданному замедлению выполнения шагов. Используйте ключ if: для пропуска таких шагов при выполнении только на docs-only изменениях.
Также следует избегать багов при shell-эскейпинге переменных в multi-line скриптах. Например, вместо использования $VAR следует использовать "$VAR", чтобы избежать проблем с интерпретацией переменных.