Создание локального Composite Action в GitHub Actions: Полное руководство

Автоматизация процессов разработки — это не просто тренд, а необходимость для современного инженера. GitHub Actions предоставляет мощный инструментарий для создания CI/CD пайплайнов, но по мере роста проекта файлы конфигурации (workflow.yaml) могут превращаться в огромные, трудночитаемые «простыни» кода.

Одним из лучших способов навести порядок в своих воркфлоу является использование Composite Actions. В этой статье мы разберем, как создать локальный композитный экшен внутри вашего репозитория, чтобы инкапсулировать логику и сделать код чище.

Что такое Composite Action?

Composite Action — это тип расширения GitHub Actions, который позволяет объединить несколько шагов (steps) в один кастомный экшен. Это идеальное решение, если вы ловите себя на мысли, что копируете одни и те же 10-20 строк кода из одного workflow в другой (например, установку зависимостей с кэшированием).

Преимущества композитных экшенов:

• DRY (Don’t Repeat Yourself): Пишем логику один раз, используем везде.
• Чистота кода: Основной файл воркфлоу сокращается до нескольких строк.
• Локальное использование: Вам не нужно создавать отдельный публичный репозиторий, экшен может жить прямо в папке вашего текущего проекта.

Структура локального экшена

Чтобы GitHub распознал ваш кастомный экшен, необходимо соблюдать строгую структуру каталогов. Все экшены должны располагаться в директории .github/actions/.

Пример структуры:

.github/
  └── actions/
      └── my-custom-action/
          └── action.yml

Ключевым файлом является action.yml (или action.yaml). Именно в нем описывается вся логика, входные и выходные параметры.

Пошаговое создание Composite Action

1. Описание метаданных

Каждый экшен начинается с заголовка и описания. Это помогает понять, за что отвечает данный блок кода.

name: 'Cache and Install Node Modules'
description: 'Установка зависимостей с использованием кэширования'

2. Определение логики запуска (runs)

Для композитных экшенов обязательным является указание параметра using: "composite". В отличие от обычных workflow, здесь нет триггера on, так как экшен вызывается принудительно.

Важный нюанс: В композитных экшенах для каждого шага с командой run необходимо явно указывать оболочку (shell), например bash.

runs:
  using: "composite"
  steps:
    - name: Cache node modules
      uses: actions/cache@v3
      with:
        path: ~/.npm
        key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}

    - name: Install dependencies
      run: npm install
      shell: bash

3. Использование входных параметров (inputs)

Чтобы сделать экшен гибким, добавьте параметры. Например, можно управлять включением или выключением кэширования через переменную.

inputs:
  enable-cache:
    description: 'Включить кэширование?'
    required: false
    default: 'true'

В коде самого экшена к этим параметрам можно обращаться через контекст ${{ inputs.enable-cache }}.

Как вызвать локальный экшен в Workflow

После того как файл action.yml готов, его можно вызвать из основного воркфлоу, указав относительный путь к папке экшена.

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Run my local action
        uses: ./.github/actions/my-custom-action
        with:
          enable-cache: 'false'

Обратите внимание: перед использованием локального экшена обязательно должен идти шаг actions/checkout, чтобы GitHub Actions «увидел» файлы в вашем репозитории.

Выходные параметры (outputs)

Экшены могут не только принимать данные, но и возвращать их. Это полезно, если следующий шаг в вашем основном пайплайне зависит от результата работы экшена (например, статус сборки или путь к артефактам).

Определяются они в блоке outputs в action.yml, а значения передаются через стандартный механизм echo "name=value >> $GITHUB_OUTPUT".

Заключение

Локальные Composite Actions — это мощный инструмент для тех, кто хочет писать поддерживаемый и профессиональный код в GitHub Actions. Они позволяют скрыть сложную логику «под капот», оставляя ваши основные файлы автоматизации чистыми и понятными.

Внедряйте этот подход в свои проекты на GitHub, и ваш процесс CI/CD станет на порядок эффективнее.

Автор: Александр Сокирка

Занимаюсь веб разработкой с 2007 года. Имею большой опыт в веб-дизайне и разработке сайтов. Являюсь автором YouTube канала Быть Программистом. Основатель бренда Aletheme и автор тем для WordPress на маркетплэйсе Envato. С 2017 года занимаюсь обучением людей желающим стать программистами. Мои обучающие программы можно найти на этом сайте или на Udemy.