참고: GitHub 호스트 실행기는 현재 GitHub Enterprise Server에서 지원되지 않습니다. GitHub public roadmap에 예정된 향후 지원에 대해 자세히 알아볼 수 있습니다.
식 정보
식을 사용하여 워크플로 파일에서 환경 변수를 프로그래밍 방식으로 설정하고 컨텍스트에 액세스할 수 있습니다. 식은 리터럴 값, 컨텍스트에 대한 참조 또는 함수의 조합일 수 있습니다. 연산자를 사용하여 리터럴, 컨텍스트 참조, 함수를 결합할 수 있습니다. 컨텍스트에 대한 자세한 내용은 "워크플로 실행에 대한 컨텍스트 정보에 액세스" 항목을 참조하세요.
식은 일반적으로 워크플로 파일에서 조건부 if
키워드와 함께 사용하여 단계를 실행해야 하는지 여부를 결정합니다. if
조건이 true
인 경우 단계가 실행됩니다.
특정 구문을 사용하여 GitHub에게 식을 문자열로 처리하는 대신 평가하도록 지시해야 합니다.
${{ <expression> }}
참고: 이 규칙의 예외는 if
절에서 식을 사용하는 경우이며, 필요에 따라 일반적으로 ${{
및 }}
을(를) 생략할 수 있습니다. if
조건부에 대한 자세한 내용은 "GitHub Actions에 대한 워크플로 구문" 항목을 참조하세요.
경고: 워크플로 및 작업을 만들 때 코드가 가능한 공격자의 신뢰할 수 없는 입력을 실행할 수 있는지 항상 고려해야 합니다. 공격자가 자신의 악성 콘텐츠를 삽입할 수 있으므로 특정 컨텍스트는 신뢰할 수 없는 입력으로 처리되어야 합니다. 자세한 내용은 "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!' }}
연산자
연산자 | 설명 |
---|---|
( ) | 논리적 그룹화 |
[ ] | 인덱스 |
. | 속성 참조 해제 |
! | Not |
< | 보다 작음 |
<= | 작거나 같음 |
> | 보다 큼 |
>= | 크거나 같음 |
== | 같음 |
!= | 같지 않음 |
&& | 및 |
|| | 또는 |
참고:
- 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' |
숫자 | 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
을 사용하여 다음 작업으로 전달합니다.
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
을 사용하여 환경 변수를 문자열에서 부울 또는 정수로 변환합니다.
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
를 사용할 수 있습니다.
경고: 심각한 오류로 인해 발생할 수 있는 작업(예시: 원본 가져오기)에 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"],
]
개체는 순서를 유지하지 않으므로 출력 순서를 보장할 수 없습니다.