Выражения

Сведения о выражениях

С помощью выражений можно программно задавать переменные среды в файлах рабочих процессов и контекстах доступа. Выражение представляет собой сочетание литералов, ссылок на контекст и функций, которые соединяются с помощью операторов. Дополнительные сведения о контекстах см. в разделе Контексты.

Выражения обычно используются с условным оператором if в файле рабочего процесса для определения того, следует ли выполнять шаг или нет. Если выражение в условии if равно true, шаг выполняется.

Чтобы в GitHub выражение вычислялось, а не считалось строкой, необходимо использовать особый синтаксис.

${{ <expression> }}

При использовании выражений в условной директиве if можно пропустить синтаксис выражения (${{ }}), так как GitHub автоматически обрабатывает условную директиву if как выражение. Дополнительные сведения об условных выражениях if см. в разделе «Синтаксис рабочего процесса для GitHub Actions».

Пример выражения в условном операторе if

steps:
  - uses: actions/hello-world-javascript-action@v1.1
    if: ${{ <expression> }}

Пример настройки переменной среды

env:
  MY_ENV_VAR: ${{ <expression> }}

Литералы

В выражении можно использовать типы данных boolean, null, number и string.

Тип данных	Литерал
boolean	true или false
null	null
number	Любой числовой формат, поддерживаемый JSON.
string	Заключать строки в скобки ${{ и }} необязательно. Однако если вы решите это сделать, используйте одинарные кавычки (') вокруг строки. Чтобы использовать литерал в виде одинарной кавычки, экранируйте его с помощью дополнительной одинарной кавычки (''). Если заключить такой литерал в двойные кавычки ("), возникнет ошибка.

Пример

env:
  myNull: ${{ null }}
  myBoolean: ${{ false }}
  myIntegerNumber: ${{ 711 }}
  myFloatNumber: ${{ -9.2 }}
  myHexNumber: ${{ 0xff }}
  myExponentialNumber: ${{ -2.99e-2 }}
  myString: Mona the Octocat
  myStringInBraces: ${{ 'It''s open source!' }}

Операторы

Оператор	Описание
( )	Логическое группирование
[ ]	Индекс
.	Разыменование свойства
!	Not
<	Меньше чем
<=	Меньше или равно
>	Больше чем
>=	Больше или равно
==	Равно
!=	Не равно
&&	And
||	либо

GitHub выполняет нестрогое сравнение.

• Если типы не совпадают, GitHub приводит их к числовому типу. Для этого в GitHub используются следующие преобразования:

  Тип	Результат
  NULL	0
  Логическое значение	true возвращает 1 false возвращает 0
  Строка	Преобразуется в любой допустимый числовой формат JSON, в противном случае дает значение NaN. Примечание. Для пустой строки возвращается 0.
  Array	NaN
  Объект	NaN

• Сравнение одного значения NaN с другим NaN не дает true. Дополнительные сведения см. в разделе о свойствах NaN в Mozilla.

• При сравнении строк в GitHub регистр не учитывается.

• Объект и массив считаются равными, только если это один экземпляр.

Функции

В GitHub предлагается набор встроенных функций, которые можно использовать в выражениях. Чтобы выполнить сравнение, некоторые функции приводят значения к строковому типу. Для этого в GitHub используются следующие преобразования:

Тип	Результат
NULL	''
Логическое значение	'true' или 'false'
Number	Десятичный формат, экспоненциальная запись для больших чисел
Array	Массивы не преобразуются в строку
Объект	Объекты не преобразуются в строку

contains

contains( search, item )

Возвращает true, если search содержит item. Если search является массивом, эта функция возвращает значение true, когда item является элементом в массиве. Если search является строкой, эта функция возвращает значение true, когда item является подстрокой search. В этой функции регистр не учитывается. Приводит значения к строковому типу.

Пример использования строки

contains('Hello world', 'llo') возвращает true.

Пример использования фильтра объектов

contains(github.event.issue.labels.*.name, 'bug') возвращает true, если проблема, связанная с событием, имеет метку "bug" (ошибка).

Дополнительные сведения см. в разделе Фильтры объектов.

Пример сопоставления массива строк

Вместо записи github.event_name == "push" || github.event_name == "pull_request" можно использовать contains() с fromJSON(), чтобы проверить, содержит ли массив строк item.

Например, contains(fromJSON('["push", "pull_request"]'), github.event_name) возвращает true, если github.event_name имеет значение "push" или "pull_request".

startsWith

startsWith( searchString, searchValue )

Возвращает значение true, когда searchString начинается с searchValue. В этой функции регистр не учитывается. Приводит значения к строковому типу.

Пример

startsWith('Hello world', 'He') возвращает true.

endsWith

endsWith( searchString, searchValue )

Возвращает значение true, если searchString заканчивается на searchValue. В этой функции регистр не учитывается. Приводит значения к строковому типу.

Пример

endsWith('Hello world', 'ld') возвращает true.

format

format( string, replaceValue0, replaceValue1, ..., replaceValueN)

Заменяет значения в строке string на значение переменной replaceValueN. Переменные в string указываются с помощью синтаксиса {N}, где N является целым числом. Необходимо указать хотя бы одно значение replaceValue и string. Максимальное количество переменных (replaceValueN) не ограничивается. Чтобы указать фигурную скобку, экранируйте ее еще одной фигурной скобкой.

Пример

format('Hello {0} {1} {2}', 'Mona', 'the', 'Octocat')

Возвращает «Hello Mona the Octocat».

Пример экранирования фигурных скобок

format('{{Hello {0} {1} {2}!}}', 'Mona', 'the', 'Octocat')

Возвращает «{Hello Mona the Octocat!}».

join

join( array, optionalSeparator )

Значением array может быть массив или строка. Все значения в array сцепляются в строку. Между сцепленными значениями вставляется разделитель optionalSeparator. Если он не указан, используется разделитель по умолчанию — ,. Приводит значения к строковому типу.

Пример

join(github.event.issue.labels.*.name, ', ') может вернуть «bug, help wanted» (ошибка, требуется помощь)

toJSON

toJSON(value)

Возвращает значение value в правильном формате JSON. С помощью этой функции можно отлаживать данные, предоставленные в контекстах.

Пример

toJSON(job) может вернуть { "status": "Success" }

fromJSON

fromJSON(value)

Возвращает объект JSON или тип данных JSON для value. С помощью этой функции можно представить объект JSON в виде вычисляемого выражения или преобразовать переменные среды из строки.

Пример возврата объекта JSON

Этот рабочий процесс задает матрицу JSON в одном задании и передает ее следующему заданию с помощью выходных данных и функции fromJSON.

name: build
on: push
jobs:
  job1:
    runs-on: ubuntu-latest
    outputs:
      matrix: ${{ steps.set-matrix.outputs.matrix }}
    steps:
      - id: set-matrix
        run: echo "::set-output name=matrix::{\"include\":[{\"project\":\"foo\",\"config\":\"Debug\"},{\"project\":\"bar\",\"config\":\"Release\"}]}"
  job2:
    needs: job1
    runs-on: ubuntu-latest
    strategy:
      matrix: ${{ fromJSON(needs.job1.outputs.matrix) }}
    steps:
      - run: build

Пример возврата типа данных JSON

Этот рабочий процесс с помощью функции fromJSON преобразует переменные среды из строки в логическое значение или целое число.

name: print
on: push
env:
  continue: true
  time: 3
jobs:
  job1:
    runs-on: ubuntu-latest
    steps:
      - continue-on-error: ${{ fromJSON(env.continue) }}
        timeout-minutes: ${{ fromJSON(env.time) }}
        run: echo ...

hashFiles

hashFiles(path)

Возвращает один хэш для набора файлов по шаблону пути path. Вы можете указать один шаблон path или несколько шаблонов path, разделенных запятыми. Путь path указывается относительно каталога GITHUB_WORKSPACE и может включать только файлы внутри GITHUB_WORKSPACE. Эта функция вычисляет отдельный хэш SHA-256 для каждого подходящего файла, а затем с помощью этих хэшей вычисляет окончательный хэш SHA-256 для набора файлов. Если по шаблону path файлы отсутствуют, функция возвращает пустую строку. Дополнительные сведения о SHA-256 см. в разделе «SHA-2».

Для сопоставления с именами файлов можно использовать подстановочные знаки. В Windows при сопоставлении по шаблону регистр не учитывается. Дополнительные сведения о поддерживаемых подстановочных знаках см. в разделе «Синтаксис рабочего процесса для GitHub Actions».

Пример с одним шаблоном

Соответствует любому файлу package-lock.json в репозитории.

hashFiles('**/package-lock.json')

Пример с несколькими шаблонами

Создает хэш для всех файлов package-lock.json и Gemfile.lock в репозитории.

hashFiles('**/package-lock.json', '**/Gemfile.lock')

Функции проверки состояния

Следующие функции проверки состояния можно использовать в качестве выражений в условных операторах if. Если не включить ни одну из этих функций, применяется проверка состояния по умолчанию success(). Дополнительные сведения об условных операторах if см. в разделе «Синтаксис рабочего процесса для GitHub Actions» и «Синтаксис метаданных для составных действий GitHub».

Успешное завершение

Возвращает значение true, если ни один из предыдущих шагов не завершился сбоем или не был отменен.

Пример

steps:
  ...
  - name: The job has succeeded
    if: ${{ success() }}

always

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

Пример

if: ${{ always() }}

cancelled

Возвращает значение true, если рабочий процесс был отменен.

Пример

if: ${{ cancelled() }}

ошибка

Возвращает значение true, если любой предыдущий шаг задания завершается сбоем. При наличии цепочки зависимых заданий, функция failure() возвращает значение true, если сбоем завершается любое предыдущее задание.

Пример

steps:
  ...
  - name: The job has failed
    if: ${{ failure() }}

сбой с условиями

Вы можете включить дополнительные условия для шага, выполняемого после сбоя, но необходимо по-прежнему включить failure() для переопределения проверки состояния по умолчанию для success(), которая автоматически применяется к условиям if, не содержащим функцию проверки состояния.

Пример

steps:
  ...
  - name: Failing step
    id: demo
    run: exit 1
  - name: The demo step has failed
    if: ${{ failure() && steps.demo.conclusion == 'failure' }}

Фильтры объектов

С помощью записи * можно применить фильтр и подобрать соответствующие элементы из коллекции.

Например, рассмотрим массив объектов с именем fruits.

[
  { "name": "apple", "quantity": 1 },
  { "name": "orange", "quantity": 2 },
  { "name": "pear", "quantity": 1 }
]

Фильтр fruits.*.name возвращает массив [ "apple", "orange", "pear" ].

Синтаксис * также можно использовать для объекта. Например, допустим, у вас есть объект с именем vegetables.

{
  "scallions":
  {
    "colors": ["green", "white", "red"],
    "ediblePortions": ["roots", "stalks"],
  },
  "beets":
  {
    "colors": ["purple", "red", "gold", "white", "pink"],
    "ediblePortions": ["roots", "stems", "leaves"],
  },
  "artichokes":
  {
    "colors": ["green", "purple", "red", "black"],
    "ediblePortions": ["hearts", "stems", "leaves"],
  },
}

Применение фильтра vegetables.*.ediblePortions может дать следующий результат:

[
  ["roots", "stalks"],
  ["hearts", "stems", "leaves"],
  ["roots", "stems", "leaves"],
]

В объектах значения не являются упорядоченными, поэтому в выходных данных какой-то определенный порядок не гарантируется.