워크플로 및 작업에서 식 평가

식 정보

식을 사용하여 워크플로 파일에서 환경 변수를 프로그래밍 방식으로 설정하고 컨텍스트에 액세스할 수 있습니다. 식은 리터럴 값, 컨텍스트에 대한 참조 또는 함수의 조합일 수 있습니다. 연산자를 사용하여 리터럴, 컨텍스트 참조, 함수를 결합할 수 있습니다. 컨텍스트에 대한 자세한 내용은 "워크플로 실행에 대한 컨텍스트 정보에 액세스" 항목을 참조하세요.

식은 일반적으로 워크플로 파일에서 조건부 if 키워드와 함께 사용하여 단계를 실행해야 하는지 여부를 결정합니다. if 조건이 true인 경우 단계가 실행됩니다.

특정 구문을 사용하여 GitHub에게 식을 문자열로 처리하는 대신 평가하도록 지시해야 합니다.

${{ <expression> }}

Note

이 규칙의 예외는 if 절에서 식을 사용하는 경우이며, 필요에 따라 일반적으로 ${{ 및 }}를 생략할 수 있습니다. if 조건부에 대한 자세한 내용은 "GitHub Actions에 대한 워크플로 구문" 항목을 참조하세요.

Warning

워크플로 및 작업을 만들 때 코드가 가능한 공격자로부터 신뢰할 수 없는 입력을 실행할 수 있는지 항상 고려해야 합니다. 공격자가 자신의 악성 콘텐츠를 삽입할 수 있으므로 특정 컨텍스트는 신뢰할 수 없는 입력으로 처리되어야 합니다. 자세한 내용은 "GitHub Actions에 대한 보안 강화" 항목을 참조하세요.

환경 변수 설정 예시

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

리터럴

식의 일부로 boolean, null, number 또는 string 데이터 형식을 사용할 수 있습니다.

데이터 형식	리터럴 값
`boolean`	`true` 또는 `false`
`null`	`null`
`number`	JSON에서 지원하는 모든 숫자 형식입니다.
`string`	`${{` 및 `}}`에 문자열을 묶을 필요가 없습니다. 그러나 문자열을 묶는 경우 문자열 주위에 작은따옴표(`'`)를 사용해야 합니다. 리터럴 작은따옴표를 사용하려면 추가 작은따옴표(`''`)를 사용하여 리터럴 작은따옴표를 이스케이프합니다. 큰따옴표(`"`)로 래핑하면 오류가 throw됩니다.

조건부에서 falsy 값(false, 0, -0, "", '', null)은 false로 강제 변환되고 truthy 값(true인 값 및 falsy가 아닌 기타 값)은 true로 강제 변환됩니다.

리터럴 예시

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!' }}

연산자

연산자	설명
`( )`	논리적 그룹화
`[ ]`	Index
`.`	속성 참조 해제
`!`	Not
`<`	보다 작음
`<=`	작거나 같음
`>`	보다 큼
`>=`	크거나 같음
`==`	같음
`!=`	같지 않음
`&&`	및
`\|\|`	또는

Note

GitHub 는 문자열을 비교할 때 대/소문자를 무시합니다.
steps.<step_id>.outputs.<output_name>은 문자열로 평가됩니다. 특정 구문을 사용하여 GitHub에게 식을 문자열로 처리하는 대신 평가하도록 지시해야 합니다. 자세한 내용은 “워크플로 실행에 대한 컨텍스트 정보에 액세스” 항목을 참조하세요.
숫자 비교의 경우 함수를 fromJSON() 사용하여 문자열을 숫자로 변환할 수 있습니다. fromJSON() 함수에 대한 자세한 내용은 "fromJSON"을 참조하세요.

GitHub은(는) 느슨한 동등 비교를 수행합니다.

형식이 일치하지 않으면 GitHub은 형식을 숫자로 강제 변환합니다. GitHub은(는) 이러한 변환을 사용하여 데이터 형식을 숫자로 캐스팅합니다.

형식	결과
Null	`0`
Boolean	true``1를 반환합니다 false``0를 반환합니다
문자열	모든 유효한 JSON 숫자 형식에서 구문 분석됩니다. 그렇지 않으면 `NaN`입니다. 참고: 빈 문자열이 `0`을 반환합니다.
배열	`NaN`
Object	`NaN`

NaN이 관계형 비교(>, <, >=, <=)의 피연산자 중 하나인 경우 결과는 항상 false입니다. 자세한 내용은 "NaN Mozilla 문서"를 참조하세요.
GitHub은(는) 문자열을 비교할 때 대/소문자를 무시합니다.
개체와 배열은 동일한 인스턴스일 때만 동일하게 간주됩니다.

GitHub은(는) 식에 사용할 수 있는 동작과 같은 3항 연산자를 제공합니다. 이러한 방식으로 3항 연산자를 사용하면 가능한 각 옵션에 대해 별도의 if-else 블록을 작성하지 않고도 조건에 따라 환경 변수의 값을 동적으로 설정할 수 있습니다.

예시

env:
  MY_ENV_VAR: ${{ github.ref == 'refs/heads/main' && 'value_for_main_branch' || 'value_for_other_branches' }}

이 예시에서는 3항 연산자를 사용하여 GitHub 참조가 설정 refs/heads/main 되었는지 여부에 따라 환경 변수의 MY_ENV_VAR 값을 설정합니다. 이 경우 변수는 value_for_main_branch로 설정됩니다. 그렇지 않으면 value_for_other_branches로 설정됩니다. && 뒤의 첫 번째 값은 반드시 truthy여야 합니다. 그렇지 않으면 || 뒤에 오는 값은 항상 반환됩니다.

함수

GitHub은 식에서 사용할 수 있는 기본 제공 함수 집합을 제공합니다. 일부 함수는 값을 문자열로 캐스팅하여 비교를 수행합니다. GitHub은(는) 이러한 변환을 사용하여 데이터 형식을 문자열로 캐스팅합니다.

형식	결과
Null	`''`
Boolean	`'true'` 또는 `'false'`
number	10진수 형식, 큰 숫자의 지수
배열	배열이 문자열로 변환되지 않음
Object	개체가 문자열로 변환되지 않음

contains

contains( search, item )

search이 item을 포함하는 경우 true를 반환합니다. search가 배열이면 이 함수는 item이 배열의 요소인 경우 true를 반환합니다. search이 문자열이면 이 함수는 item이 search의 하위 문자열인 경우 true를 반환합니다. 이 함수는 대/소문자를 구분하지 않습니다. 값을 문자열로 캐스팅합니다.

문자열을 사용하는 예시

contains('Hello world', 'llo')은(는) true을(를) 반환합니다.

개체 필터를 사용하는 예시

contains(github.event.issue.labels.*.name, 'bug')은 이벤트와 관련된 문제에 "버그" 레이블이 있는 경우 true를 반환합니다.

자세한 내용은 "개체 필터"를 참조하세요.

문자열 배열과 일치하는 예시

github.event_name == "push" || github.event_name == "pull_request"를 쓰는 대신 fromJSON()과 함께 contains()을(를) 사용하여 문자열 배열에 item이 포함되어 있는지 확인할 수 있습니다.

예를 들어 contains(fromJSON('["push", "pull_request"]'), github.event_name)은 github.event_name이 “push” 또는 “pull_request”인 경우 true을(를) 반환합니다.

startsWith

startsWith( searchString, searchValue )

searchString이 searchValue로 시작하면 true을(를) 반환합니다. 이 함수는 대/소문자를 구분하지 않습니다. 값을 문자열로 캐스팅합니다.

`startsWith`의 예시

startsWith('Hello world', 'He')은(는) true을(를) 반환합니다.

endsWith

endsWith( searchString, searchValue )

true이 searchString으로 끝나면 searchValue을(를) 반환합니다. 이 함수는 대/소문자를 구분하지 않습니다. 값을 문자열로 캐스팅합니다.

`endsWith`의 예시

endsWith('Hello world', 'ld')은(는) true을(를) 반환합니다.

format

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

string의 값을 replaceValueN 변수로 바꿉니다. string의 변수는 {N} 구문을 사용하여 지정됩니다. 여기서 N은 정수입니다. replaceValue 및 string을 하나 이상 지정해야 합니다. 사용할 수 있는 변수(replaceValueN)의 최대값은 없습니다. 이중 중괄호를 사용하여 중괄호를 이스케이프합니다.

`format`의 예시

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`의 예시

join(github.event.issue.labels.*.name, ', ')은 ‘버그, 도움 요청’을 반환할 수 있습니다.

toJSON

toJSON(value)

value의 자동 서식 지정 JSON 표현을 반환합니다. 이 함수를 사용하여 컨텍스트에 제공된 정보를 디버그할 수 있습니다.

`toJSON`의 예시

toJSON(job)은 { "status": "success" }를 반환할 수 있습니다.

fromJSON

fromJSON(value)

value에 대한 JSON 객체 또는 JSON 데이터 형식을 반환합니다. 이 함수를 사용하여 JSON 개체를 평가 식으로 제공하거나 문자열, 부울, null 값, 배열 및 개체와 같이 JSON 또는 JavaScript로 표시할 수 있는 데이터 형식을 변환할 수 있습니다.

JSON 개체를 반환하는 예시

이 워크플로는 한 작업에서 JSON 매트릭스를 설정하고 출력 및 fromJSON을 사용하여 다음 작업으로 전달합니다.

YAML

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

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

JSON 데이터 형식을 반환하는 예시

이 워크플로는 fromJSON을 사용하여 환경 변수를 문자열에서 부울 또는 정수로 변환합니다.

YAML

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 ...

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 ...

워크플로는 fromJSON() 함수를 사용하여 환경 변수 continue를 문자열에서 부울로 변환하여 오류 발생 시 계속할지 여부를 결정할 수 있습니다. 마찬가지로 time 환경 변수를 문자열에서 정수로 변환하여 작업에 대한 시간 제한을 분 단위로 설정합니다.

hashFiles

hashFiles(path)

path 패턴과 일치하는 파일 세트에 대한 단일 해시를 반환합니다. 쉼표로 구분된 단일 path 패턴 또는 여러 path 패턴을 제공할 수 있습니다. path은 GITHUB_WORKSPACE 디렉터리에 상대적이며 GITHUB_WORKSPACE 내부의 파일만 포함할 수 있습니다. 이 함수는 일치하는 각 파일에 대한 개별 SHA-256 해시를 계산한 다음 해당 해시를 사용하여 파일 집합에 대한 최종 SHA-256 해시를 계산합니다. path 패턴이 파일과 일치하지 않으면 빈 문자열을 반환합니다. SHA-256에 대한 자세한 내용은 "SHA-2"를 참조하세요.

패턴 일치 문자를 사용하여 파일 이름을 일치시킬 수 있습니다. hashFiles의 패턴 일치는 glob 패턴 일치를 따르며 Windows에서는 대/소문자를 구분하지 않습니다. 지원되는 패턴 일치 문자에 대한 자세한 내용은 @actions/glob 설명서에서 패턴 섹션을 참조하세요.

단일 패턴을 사용하는 예시

리포지토리의 모든 package-lock.json 파일과 일치합니다.

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

여러 패턴이 있는 예시

리포지토리에 있는 모든 package-lock.json 및 Gemfile.lock 파일에 대한 해시를 만듭니다.

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

상태 검사 함수

다음 상태 검사 함수를 if 조건의 식으로 사용할 수 있습니다. 이러한 함수 중 하나를 포함하지 않는 한 success() 기본 상태 검사가 적용됩니다. 조건부에 대한 if 자세한 내용은 "GitHub Actions에 대한 워크플로 구문" 및 "AUTOTITLE" 항목을 참조하세요.

성공

이전 단계가 모두 성공한 경우 true를 반환합니다.

`success`의 예시

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

항상

취소된 경우에도 단계가 항상 실행되고 true가 반환되도록 합니다. 이 always 식은 작업이 취소된 경우에도 실행할 것으로 예상되는 단계 수준 또는 태스크에서 가장 잘 사용됩니다. 예를 들어 작업이 취소된 경우에도 로그를 보내는 데 always를 사용할 수 있습니다.

Warning

중요한 오류가 발생할 수 있는 작업(예: 원본 가져오기)에는 always를 사용하지 않아야 합니다. 그렇지 않으면 시간 초과될 때까지 워크플로가 중단될 수 있습니다. 성공 또는 실패에 관계없이 작업 또는 단계를 실행하려면 권장되는 대안을 사용합니다. if: ${{ !cancelled() }}

`always`의 예시

if: ${{ always() }}

취소됨

워크플로가 취소된 경우 true을(를) 반환합니다.

`cancelled`의 예시

if: ${{ cancelled() }}

실패

작업의 이전 단계가 실패하면 true을(를) 반환합니다. 종속 작업 체인이 있는 경우 상위 작업이 실패하면 failure()가 true을(를) 반환합니다.

`failure`의 예시

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

조건이 있는 오류

실패 후 실행할 단계에 대한 추가 조건을 포함할 수 있지만 상태 확인 기능이 포함되지 않은 if 조건에 자동으로 적용되는 success()의 기본 상태 확인을 재정의하려면 failure()을(를) 계속 포함해야 합니다.

조건이 있는 `failure`의 예시

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"],
]

개체는 순서를 유지하지 않으므로 출력 순서를 보장할 수 없습니다.

이 문서의 내용