Этот пост является вторым в серии рабочих процессов GitHub Actions для проектов Java. В нем я объясняю рабочий процесс GitHub Actions, который я запускаю для push-уведомлений и запросов на вытягивание, для создания, тестирования, создания значков покрытия и комментирования процентов покрытия в запросах на вытягивание. Состояние этого рабочего процесса также используется в качестве обязательной проверки запроса на вытягивание (например, сборка, включающая модульные тесты, должна пройти, чтобы разрешить слияние).

Оглавление:


Рабочий процесс шаг за шагом

Я собираюсь пройти весь рабочий процесс от начала до конца.


Запуск рабочего процесса

Мой рабочий процесс сборки настроен на запуск на основе нескольких событий. Это включает в себя pull_request событие для выполнения всех запросов на вытягивание, и workflow_dispatch события, что позволяет мне запускать его вручную, если это необходимо. Я также настроил его для работы на push событий, но только когда отправка включает изменения в файлы Java, Maven pom.xml для проекта или при изменении самого рабочего процесса сборки. Причина, по которой я ограничиваю запуск при отправке, заключается в том, что я не трачу циклы на бегун, если я просто вношу изменения в файл readme или другие подобные незначительные изменения, которые не влияют на саму сборку. Я не делаю этого ограничения на запросы на вытягивание, потому что я использую этот рабочий процесс в качестве обязательной проверки запроса на вытягивание, поэтому мне нужно, чтобы он выполнялся, даже если PR не включает изменения исходного кода, чтобы предотвратить блокировку PR.

name: build

on:
  push:
    branches: [ master ]
    paths: [ '**.java', '.github/workflows/build.yml', 'pom.xml' ]
  pull_request:
    branches: [ master ]
  workflow_dispatch:
Войти в полноэкранный режим

Выйти из полноэкранного режима


Проверка репозитория

Рабочий процесс имеет одно задание buildработает в Ubuntu и начинается с обычного шага проверки, используя actions/checkout действие.

jobs:
  build:

    runs-on: ubuntu-latest

    steps:
    - name: Checkout
      uses: actions/checkout@v3
Войти в полноэкранный режим

Выйти из полноэкранного режима


Проверка ветки значков

На одном из последующих шагов рабочего процесса создаются значки покрытия, которые затем сохраняются в репозитории. Однако значки хранятся в отдельной ветке, которую я назвал badges, а не ветвь по умолчанию. Я делаю это так, потому что моя ветка по умолчанию защищена. Чтобы отправить значки в ветку по умолчанию, мне нужно будет использовать токен личного доступа с разрешениями, повышенными над разрешениями по умолчанию для GITHUB_TOKEN. Я не хочу этого делать из соображений безопасности. Я также не хочу использовать какие-либо другие известные мне подходы к обходу правил защиты ветвей в рабочем процессе GitHub Actions.

Вместо этого я использую выделенную ветку, единственной целью которой является хранение значков покрытия, которые я все еще могу встроить в readme в ветке по умолчанию. Так что мой рабочий процесс имеет второй actions/checkout шаг, чтобы проверить badges ответвление к badges каталог, который я вложил в другой, как показано ниже:

    - name: Checkout badges branch to a badges directory nested inside first checkout
      uses: actions/checkout@v3
      with:
        ref: badges
        path: badges
Войти в полноэкранный режим

Выйти из полноэкранного режима


Настройка Java

Далее я использую actions/setup-java действие по настройке дистрибутива Adoptium для Java 17.

    - name: Set up JDK 17
      uses: actions/setup-java@v3
      with:
        distribution: 'adopt'
        java-version: '17'
Войти в полноэкранный режим

Выйти из полноэкранного режима


Сборка, включая создание отчета о покрытии кода

Далее мы собираем библиотеку с помощью Maven. Я использую JaCoCo для покрытия кода. Я настроил плагин JaCoCo Maven в профиле Maven с идентификатором coverage в моем pom.xml. См. мой предыдущий пост об использовании профилей Maven, который включал пример того, как я настраиваю покрытие кода в профиле Maven. Чтобы активировать этот профиль и создать отчет о покрытии кода, я использую параметр командной строки -Pcoverage.

    - name: Build with Maven
      run: mvn -B package -Pcoverage
Войти в полноэкранный режим

Выйти из полноэкранного режима


Создание значков покрытия

Для создания значков покрытия я использую действие GitHub, которое я разрабатываю и поддерживаю, jacoco-значок-генератор. Я писал об этом GitHub Action здесь, в DEV, в прошлом. Вот один из таких постов:

При настройке использования этого действия в этом рабочем процессе я использовал его badges-directory введите, чтобы изменить каталог, в котором создаются значки, чтобы он соответствовал каталогу, содержащему мою предыдущую вложенную проверку badges ответвляться. Кроме того, действие по умолчанию создает только значок покрытия инструкций, поэтому я дополнительно использую generate-branches-badge: true чтобы также создать значок покрытия филиалов. Это действие также может дополнительно генерировать простой файл JSON, содержащий проценты покрытия, поэтому я активирую его с помощью generate-summary: true. Один из моих последних шагов использует эту сводку JSON при комментировании запросов на вытягивание. После jacoco-значок-генератор шаг ниже, я также показываю шаг, который я использую для записи процентов покрытия в журнал запуска рабочего процесса.

    - name: Generate JaCoCo badge
      id: jacoco
      uses: cicirello/jacoco-badge-generator@v2
      with:
        badges-directory: badges
        generate-branches-badge: true
        generate-summary: true

    - name: Log coverage percentages to workflow output
      run: |
        echo "coverage = ${{ steps.jacoco.outputs.coverage }}"
        echo "branches = ${{ steps.jacoco.outputs.branches }}"
Войти в полноэкранный режим

Выйти из полноэкранного режима


Загрузить полный отчет о покрытии как артефакт рабочего процесса

Затем я использую actions/upload-artifact действие для загрузки полного отчета о покрытии JaCoCo в качестве артефакта рабочего процесса. Таким образом, я могу загрузить его из рабочего процесса через Actions вкладку, если мне нужно увидеть подробности. Я использую Maven вместе с расположением отчетов JaCoCo по умолчанию, поэтому они находятся в каталоге target/site/jacoco/. actions/upload-artifact action создает zip-файл со всем содержимым этого каталога, который в данном случае будет включать в себя все различные отчеты JaCoCo, такие как подробный отчет в формате HTML, а также версии в формате XML и CSV.

    - name: Upload JaCoCo coverage report as a workflow artifact
      uses: actions/upload-artifact@v3
      with:
        name: jacoco-report
        path: target/site/jacoco/
Войти в полноэкранный режим

Выйти из полноэкранного режима


Подтвердите и нажмите значки покрытия

jacoco-значок-генератор генерирует значки, но не фиксирует их. На этом этапе я просто использую простой сценарий оболочки для фиксации и отправки значков. Этот шаг является условным и выполняется только в том случае, если событие, запустившее рабочий процесс, не является запросом на вытягивание (см. if: ${{ github.event_name != 'pull_request' }}). Другими словами, он работает на push а также workflow_dispatch События. Значки покрытия должны соответствовать состоянию ветки по умолчанию, поэтому фиксация значков, соответствующих покрытию запроса на вытягивание, которое может быть или не быть объединено, не имеет смысла. Если он объединен, событие push приведет к повторному запуску рабочего процесса, после чего значки покрытия будут зафиксированы. Этот шаг начинается с изменения текущего каталога на каталог, в котором badges Филиал проверен. И он фиксирует и отправляет только в том случае, если svg или же json файл изменен. Значки — это SVG, и вспомните предыдущий шаг, когда я настроил jacoco-значок-генератор чтобы дополнительно сгенерировать простой файл JSON, содержащий проценты покрытия.

    - name: Commit and push the coverage badges and summary file
      if: ${{ github.event_name != 'pull_request' }}
      run: |
        cd badges
        if [[ `git status --porcelain *.svg *.json` ]]; then
          git config --global user.name 'github-actions'
          git config --global user.email '41898282+github-actions[bot]@users.noreply.github.com'
          git add *.svg *.json
          git commit -m "Autogenerated JaCoCo coverage badges" *.svg *.json
          git push
        fi
Войти в полноэкранный режим

Выйти из полноэкранного режима


Прокомментируйте проценты покрытия в запросах на вытягивание

На этом последнем шаге я использую интерфейс командной строки GitHub, чтобы прокомментировать процент покрытия запросов на вытягивание. Этот шаг является условным, как и предыдущий, но на этот раз он выполняется только для запросов на вытягивание (см. if: ${{ github.event_name == 'pull_request' }}). Это простой сценарий оболочки. В первых нескольких строках используется jq разобрать coverage-summary.json произведено jacoco-значок-генератор, а затем создает строку с содержимым для комментария запроса на вытягивание. Затем последняя строка использует CLI GitHub для комментирования запроса на вытягивание. Интерфейс командной строки GitHub требует аутентификации через GITHUB_TOKEN передается как переменная окружения.

    - name: Comment on PR with coverage percentages
      if: ${{ github.event_name == 'pull_request' }}
      run: |
        REPORT=$(<badges/coverage-summary.json)
        COVERAGE=$(jq -r '.coverage' <<< "$REPORT")%
        BRANCHES=$(jq -r '.branches' <<< "$REPORT")%
        NEWLINE=$'\n'
        BODY="## JaCoCo Test Coverage Summary Statistics${NEWLINE}* __Coverage:__ ${COVERAGE}${NEWLINE}* __Branches:__ ${BRANCHES}"
        gh pr comment ${{github.event.pull_request.number}} -b "${BODY}"
      continue-on-error: true
      env:
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
Войти в полноэкранный режим

Выйти из полноэкранного режима

В настоящее время я настроил этот последний шаг с помощью continue-on-error: true, что предотвратит сбой выполнения рабочего процесса на этом шаге. Разрешения по умолчанию для GITHUB_TOKEN недостаточны для комментирования запросов на включение, поступающих от форков. Мне нужно повысить разрешения, предоставленные GITHUB_TOKEN для того, чтобы сделать это, что находится в моем списке дел. Даже без комментариев полные отчеты о покрытии загружаются как артефакт рабочего процесса на одном из предыдущих шагов.


Полный рабочий процесс

Вот мой полный рабочий процесс.

name: build

on:
  push:
    branches: [ master ]
    paths: [ '**.java', '.github/workflows/build.yml', 'pom.xml' ]
  pull_request:
    branches: [ master ]
  workflow_dispatch:

jobs:
  build:

    runs-on: ubuntu-latest

    steps:
    - name: Checkout
      uses: actions/checkout@v3

    - name: Checkout badges branch to a badges directory nested inside first checkout
      uses: actions/checkout@v3
      with:
        ref: badges
        path: badges

    - name: Set up JDK 17
      uses: actions/setup-java@v3
      with:
        distribution: 'adopt'
        java-version: '17'

    - name: Build with Maven
      run: mvn -B package -Pcoverage

    - name: Generate JaCoCo badge
      id: jacoco
      uses: cicirello/jacoco-badge-generator@v2
      with:
        badges-directory: badges
        generate-branches-badge: true
        generate-summary: true

    - name: Log coverage percentages to workflow output
      run: |
        echo "coverage = ${{ steps.jacoco.outputs.coverage }}"
        echo "branches = ${{ steps.jacoco.outputs.branches }}"

    - name: Upload JaCoCo coverage report as a workflow artifact
      uses: actions/upload-artifact@v3
      with:
        name: jacoco-report
        path: target/site/jacoco/

    - name: Commit and push the coverage badges and summary file
      if: ${{ github.event_name != 'pull_request' }}
      run: |
        cd badges
        if [[ `git status --porcelain *.svg *.json` ]]; then
          git config --global user.name 'github-actions'
          git config --global user.email '41898282+github-actions[bot]@users.noreply.github.com'
          git add *.svg *.json
          git commit -m "Autogenerated JaCoCo coverage badges" *.svg *.json
          git push
        fi

    - name: Comment on PR with coverage percentages
      if: ${{ github.event_name == 'pull_request' }}
      run: |
        REPORT=$(<badges/coverage-summary.json)
        COVERAGE=$(jq -r '.coverage' <<< "$REPORT")%
        BRANCHES=$(jq -r '.branches' <<< "$REPORT")%
        NEWLINE=$'\n'
        BODY="## JaCoCo Test Coverage Summary Statistics${NEWLINE}* __Coverage:__ ${COVERAGE}${NEWLINE}* __Branches:__ ${BRANCHES}"
        gh pr comment ${{github.event.pull_request.number}} -b "${BODY}"
      continue-on-error: true
      env:
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
Войти в полноэкранный режим

Выйти из полноэкранного режима


Репозитории, используемые в этом посте


Живой пример

Чтобы увидеть живой пример, обратитесь к build.yml рабочий процесс одного из моих проектов. Вот репозиторий GitHub:

Java-библиотека настраиваемых, гибридизируемых, итеративных, параллельных, стохастических и самоадаптирующихся алгоритмов локального поиска.

Chips-n-Salsa — Java-библиотека настраиваемых, гибридизуемых, итеративных, параллельных, стохастических и самоадаптирующихся алгоритмов локального поиска.

Авторское право (С) 2002-2022 Винсент Чичирелло.

Веб-сайт:

Документация по API: API/

Как цитировать

Если вы используете эту библиотеку в своих исследованиях, процитируйте следующую статью:

Чичирелло, Вирджиния, (2020). Chips-n-Salsa: Java-библиотека настраиваемых, гибридизируемых, итеративных, параллельных, стохастических и самоадаптирующихся алгоритмов локального поиска. Журнал программного обеспечения с открытым исходным кодом5(52), 2448, .

Обзор

Chips-n-Salsa — это Java-библиотека настраиваемых, гибридизуемых, итеративных, параллельных, стохастических и самоадаптирующихся алгоритмов локального поиска. Библиотека включает в себя реализации нескольких алгоритмов стохастического локального поиска, в том числе имитации отжига, альпинистов, а также конструктивных алгоритмов поиска, таких как стохастическая выборка. Chips-n-Salsa теперь также включает генетические алгоритмы, а также эволюционные алгоритмы в целом. Библиотека очень широко поддерживает имитацию отжига. Он включает в себя несколько классов для представления решений различных задач оптимизации. За…


Действие jacoco-badge-generator на GitHub

Один из шагов моего рабочего процесса использует jacoco-значок-генератор для анализа и обобщения отчета о покрытии JaCoCo, создания значков покрытия и сводного файла JSON. Вот репозиторий самого действия:

Значки покрытия и проверки покрытия запросов на вытягивание из отчетов JaCoCo в GitHub Actions.

cicirello/jacoco-badge-generator — значки покрытия и проверки покрытия запросов на вытягивание из отчетов JaCoCo в GitHub Actions.

Ознакомьтесь со всеми нашими действиями на GitHub:

О

Генератор jacoco-badge-generator можно использовать одним из двух способов: как действие GitHub или как утилиту командной строки (например, как часть сценария локальной сборки). Генератор jacoco-badge-generator анализирует jacoco.csv
из отчета о покрытии JaCoCo, вычисляет процент покрытия из Счетчики Инструкций и Филиалов JaCoCo, и создает значки для одного или обоих из них (настраивается пользователем), чтобы предоставить удобную для чтения визуальную сводку покрытия кода ваших тестовых случаев. Поведение по умолчанию напрямую генерирует значки внутри без внешних вызовов, но действие также предоставляет возможность вместо этого генерировать Защищает конечные точки JSON. Он поддерживает как базовый случай одного jacoco.csvа также многомодульные проекты, и в этом случае действие может производить значки покрытия из комбинации…


Где вы можете найти меня

Подписывайтесь на меня здесь, на DEV:

изображение чичирелло

Подпишитесь на меня на GitHub:

Винсент Чичирелло

Моя библиометрия

Моя активность на GitHub

Если вы хотите создать аналог вышеприведенному для своего собственного профиля GitHub, ознакомьтесь с cicirello/пользователь-статистик
Действие на гитхабе.

Или посетите мой сайт:

Винсент А. Чичирелло — профессор компьютерных наук в Стоктонском университете — исследователь в области искусственного интеллекта, эволюционных вычислений, коллективного интеллекта и вычислительного интеллекта, имеет докторскую степень. по робототехнике Университета Карнеги-Меллона. Он является старшим членом ACM, старшим членом IEEE, пожизненным членом AAAI, почетным членом EAI и членом SIAM.

фавикон
cicirello.org