Moa는 잡 실행 중에 동적으로 값을 구성하기 위한 표현식 언어입니다. 표현식은 ${{ }} 구분자로 둘러싸이며 GitLab Functions와 Job inputs에서 사용됩니다.

Moa는 문자열 조작, 산술, 비교, 논리 연산, 속성 접근, 함수 호출을 지원합니다.

CI/CD 표현식과의 차이점#

GitLab에는 파이프라인 생명 주기의 다른 단계에서 다른 목적을 제공하는 세 가지 표현식 구문이 있습니다.

• Rules는 잡 포함을 제어하기 위해 rules: 키워드 내에서 자체 표현식 구문을 사용합니다. 파이프라인 생성 중에 평가되며 CI/CD 변수에 대한 비교와 패턴 매칭을 지원하지만 산술을 수행하거나 런타임 상태에 접근할 수 없습니다.
• CI/CD 표현식은 $[[ ]] 구문을 사용하며 잡이 실행되기 전 파이프라인 생성 중에 평가됩니다. 이 표현식은 CI/CD 입력값, 매트릭스 값, 컴포넌트 입력값에 대한 값 대체를 수행합니다. 산술, 비교, 로직을 수행할 수 없으며 런타임 상태에 접근할 수 없습니다. 자세한 내용은 CI/CD 표현식을 참조하세요.
• Moa는 ${{ }} 구문을 사용하며 러너에 의해 잡 실행 중에 평가됩니다. Moa는 연산자, 데이터 구조, 함수 호출을 갖춘 완전한 표현식 언어입니다.

세 가지 구문 모두 동일한 파이프라인에 공존할 수 있습니다. GitLab Functions를 포함하는 CI/CD 컴포넌트는 세 가지 모두를 사용할 수 있습니다:

spec:
  inputs:
    echo_version:
      type: string
---

hi-job:
  # rules expression - evaluated when the pipeline is created
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
  run:
    - name: say_hi
      # $[[ ]] - resolved when the pipeline is created
      step: registry.gitlab.com/gitlab-org/ci-cd/runner-tools/gitlab-functions-examples/echo@$[[ inputs.echo_version ]]
      inputs:
        # ${{ }} - resolved when the job runs
        message: "Hello, ${{ vars.CI_PROJECT_NAME }}"

Moa는 파이프라인 생성 시점에 사용할 수 없는 기능이 GitLab Functions에 필요하기 때문에 별도의 언어로 존재합니다:

• 런타임 평가: 스텝 출력은 함수가 실행될 때까지 존재하지 않습니다. ${{ steps.build.outputs.image_ref }}와 같은 표현식은 실행 중에만 평가할 수 있습니다.
• 타입 값: Moa는 기본 타입(숫자, 불리언, 배열, 객체)을 보존하고 문자열로 변환하지 않고 함수 간에 전달합니다.
• 연산자와 로직: GitLab Functions는 스텝 입력값을 변수와 출력값으로 구성하기 위해 산술(major_version + 1), 비교(vulnerabilities == 0), 단락 로직(inputs.tag || "latest")이 필요합니다.
• 민감한 값 추적: Moa는 연산을 통해 민감한 값을 전파합니다. 민감한 값을 문자열에 연결하거나 함수 호출을 통해 전달하면 결과도 민감한 것으로 처리됩니다. 이는 로그와 출력에서 시크릿의 우발적인 노출을 방지합니다.

컨텍스트 참조#

표현식에서 사용할 수 있는 값은 표현식이 사용되는 위치에 따라 다릅니다.

템플릿 구문#

보간#

${{ }}에 표현식을 감싸서 평가합니다:

script:
  - echo "Hello, ${{ job.inputs.name }}"

텍스트가 표현식을 둘러싸면 결과는 항상 문자열로 변환됩니다. 여러 표현식이 단일 값에 나타날 수 있습니다:

script:
  - echo "${{ job.inputs.greeting }}, ${{ job.inputs.name }}!"

기본 타입 전달#

${{ expression }}이 주변 텍스트 없이 전체 값인 경우, 표현식은 기본 타입을 반환합니다. 기본 타입 표현식을 사용하여 숫자, 불리언, 배열, 객체와 같은 비문자열 값을 문자열로 변환하지 않고 스텝 간에 전달합니다.

inputs:
  count: ${{ steps.previous.outputs.total }}

이 예시에서 total이 숫자이면 count는 문자열 표현이 아닌 숫자를 받습니다.

Moa 표현식 이스케이프#

보간을 트리거하지 않고 텍스트에 리터럴 ${{를 포함하려면 백슬래시로 이스케이프합니다:

script:
  - echo "Use \${{ to start an expression"

이 명령은 평가 없이 Use ${{ to start an expression 텍스트를 출력합니다.

리터럴#

Null#

키워드 null은 값의 부재를 나타냅니다.

${{ null }}

불리언#

키워드 true와 false는 불리언 값을 나타냅니다.

${{ true }}
${{ false }}

숫자#

숫자는 53비트 가수 정밀도를 가진 IEEE 754 배정밀도 부동 소수점 값입니다. 정수, 소수, 과학적 표기법이 지원됩니다.

${{ 42 }}
${{ 3.14 }}
${{ 1.5e3 }}
${{ 2E-4 }}

문자열#

문자열을 큰따옴표나 작은따옴표로 감쌉니다. 두 가지 따옴표 유형은 이스케이프 시퀀스와 템플릿 표현식을 다르게 처리합니다.

큰따옴표 문자열은 템플릿 표현식과 전체 이스케이프 시퀀스 세트를 지원합니다:

큰따옴표 문자열 내부의 템플릿 표현식(${{ }})은 평가되어 문자열에 보간됩니다.

작은따옴표 문자열은 최소한의 해석이 있는 원시 문자열 리터럴입니다. 작은따옴표 문자열 내부의 템플릿 표현식은 평가되지 않습니다. 두 가지 이스케이프 시퀀스만 지원됩니다:

${{ "Hello\nWorld" }}
${{ 'It\'s a string' }}
${{ 'Literal ${{ not evaluated }}' }}

식별자#

식별자는 표현식 컨텍스트의 값을 참조합니다. 식별자는 문자 또는 밑줄로 시작하며 문자, 숫자, 밑줄을 포함할 수 있습니다. 식별자는 대소문자를 구분합니다: foo, Foo, FOO는 세 가지 다른 식별자입니다.

${{ env }}
${{ my_variable }}

식별자는 사용 가능한 컨텍스트에 대해 해결됩니다. 각 컨텍스트에서 사용 가능한 값은 컨텍스트 참조를 참조하세요.

식별자가 컨텍스트 객체를 참조하면 전체 객체가 반환됩니다. 예를 들어, ${{ vars }}는 모든 잡 변수를 객체로 반환합니다.

연산자#

산술 연산자#

산술 연산자는 숫자에 대해 작동합니다. + 연산자는 문자열도 연결합니다. 연산자는 암묵적 타입 변환을 수행하지 않으므로 "hello" + 42는 오류가 발생합니다.

0으로 나누면 오류가 발생합니다.

비교 연산자#

비교 연산자는 불리언 값을 반환합니다.

다른 타입의 값은 타입으로 비교되므로 1 == "1"은 false로 평가됩니다. 동일한 타입의 값은 다음 비교 규칙을 따릅니다:

• 숫자: 수치 비교.
• 문자열: 사전식 비교(UTF-8 바이트 순서).
• 불리언: false는 true보다 작습니다.
• 배열: 요소별 비교.
• 객체: 길이, 키, 값 순으로 비교. 키 순서는 중요하지 않습니다.
• Null: null은 null과 같습니다.

논리 연산자#

논리 연산자는 단락 평가를 사용하며 피연산자 중 하나를 반환합니다. 반드시 불리언이 아닙니다. 이 동작은 JavaScript &&와 || 연산자와 유사합니다.

|| 연산자는 기본값을 제공하는 데 사용됩니다:

${{ inputs.name || "default" }}

inputs.name이 비어 있지 않은 문자열이면 그대로 반환됩니다. 비어 있거나 null이면 "default"가 반환됩니다.

단항 연산자#

연산자 우선순위#

연산자는 최고 우선순위에서 최저 우선순위 순으로 나열됩니다. 같은 행의 연산자는 동등한 우선순위를 가집니다. 모든 이진 연산자는 왼쪽 결합입니다.

우선순위를 재정의하기 위해 괄호를 사용합니다:

${{ (1 + 2) * 3 }}

데이터 구조#

배열#

대괄호 표기법으로 배열을 만듭니다. 요소는 모든 타입이 될 수 있으며 타입을 혼합할 수 있습니다. 후행 쉼표를 사용할 수 있습니다.

${{ [1, 2, 3] }}
${{ ["a", 1, true, null] }}
${{ [] }}

객체#

중괄호 표기법으로 객체를 만듭니다. 키는 문자열로 평가되어야 합니다. 값은 모든 타입이 될 수 있습니다. 후행 쉼표가 허용됩니다.

${{ {name: "runner", version: 1} }}
${{ {"string-key": true} }}
${{ {} }}

객체 키로 사용된 베어 식별자는 변수 참조가 아닌 문자열 리터럴로 처리됩니다. 변수를 키로 사용하려면 괄호로 감쌉니다:

${{ {name: "Alice"} }}           # "name" is the string "name", not a variable reference
${{ {(obj.prop): "value"} }}     # key is the value of obj.prop, which must be a string

속성 접근#

점 표기법#

점 표기법으로 객체 속성에 접근합니다:

${{ env.HOME }}
${{ steps.build.outputs.artifact_path }}

대괄호 표기법#

인덱스로 배열 요소에 접근하거나, 문자열 키로 객체 속성에 접근합니다:

${{ my_array[0] }}
${{ my_object["property-name"] }}

속성 이름에 하이픈과 같은 특수 문자가 포함된 경우 대괄호 표기법이 필요합니다.

체이닝#

속성 접근과 함수 호출을 체인합니다:

${{ steps.build.outputs.items[0] }}

함수 호출#

이름과 괄호로 함수를 호출합니다:

${{ str(42) }}
${{ num("3.14") }}

진리성#

논리 연산자와 ! 연산자는 다음 진리성 규칙을 사용합니다:

내장 함수#

str(value)#

모든 값을 문자열 표현으로 변환합니다.

${{ str(42) }}       # "42"
${{ str(true) }}     # "true"
${{ str(null) }}     # "<null>"

num(value)#

문자열을 숫자로 변환합니다. 문자열은 유효한 수치 표현이어야 합니다.

${{ num("42") }}     # 42
${{ num("3.14") }}   # 3.14

bool(value)#

진리성을 기반으로 모든 값을 불리언으로 변환합니다.

${{ bool("hello") }}  # true
${{ bool("") }}       # false
${{ bool(0) }}        # false
${{ bool(1) }}        # true

예약어#

다음 단어는 예약되어 있으며 식별자로 사용할 수 없습니다. 잠재적인 향후 언어 기능을 위해 예약됩니다.

array, as, break, case, const, continue, default, else, fallthrough, float, for, func, function, goto, if, import, in, int, let, loop, map, namespace, number, object, package, range, return, string, struct, switch, type, var, void, while

키워드 null, true, false도 리터럴 값으로 예약됩니다.

예시#

전략 선택을 포함한 배포#

deploy job:
  when: manual
  inputs:
    environment:
      default: staging
      options: [staging, production]
      description: Target deployment environment
    strategy:
      default: rolling
      options: [rolling, blue-green, canary]
      description: Deployment strategy
    replicas:
      type: number
      default: 3
      description: Number of replicas to deploy
  image: ${{ job.inputs.environment == "production" && "deploy-tools:stable" || "deploy-tools:latest" }}
  script:
    - 'echo "Deploying to ${{ job.inputs.environment }} using ${{ job.inputs.strategy }}"'
    - deploy
        --env ${{ job.inputs.environment }}
        --strategy ${{ job.inputs.strategy }}
        --replicas ${{ str(job.inputs.replicas) }}

불리언 잡 입력값의 조건부 플래그#

test_job:
  inputs:
    coverage:
      type: boolean
      default: false
    verbose:
      type: boolean
      default: false
  script:
    - pytest ${{ job.inputs.verbose && "-v" || "" }} ${{ job.inputs.coverage && "--cov=src" || "" }}

잡 변수에서 이미지 참조 빌드#

build_job:
  run:
    - name: build
      func: ./docker-build
      inputs:
        image: ${{ vars.CI_REGISTRY + "/" + vars.CI_PROJECT_PATH + ":" + vars.CI_PIPELINE_IID }}

계속 게이트#

security_scan_job:
  run:
    - name: scan
      func: ./security-scan
    - name: gate
      func: ./quality-gate
      inputs:
        should_proceed: ${{ steps.scan.outputs.critical == 0 && steps.scan.outputs.high < 5 }}

버전 관리#

increment_version_job:
  run:
    - name: current
      func: ./find-version
    - name: bump
      func: ./bump-version
      inputs:
        new_version: ${{ str(steps.current.outputs.major + 1) + ".0.0" }}

환경별 구성#

deploy_job:
  run:
    - name: deploy
      func: ./deploy
      inputs:
        registry: ${{ (vars.CI_COMMIT_REF_NAME == "main" && "prod.registry.com") || "staging.registry.com" }}
        replicas: ${{ (vars.CI_COMMIT_REF_NAME == "main" && 5) || 2 }}

A/B 테스팅 구성#

configure_job:
  run:
    - name: configure_ab
      func: ./traffic-split
      inputs:
        variants: |
          ${{ [
            {name: "control", use_new_feature: false, weight: 90},
            {name: "experiment", use_new_feature: true, weight: 10}
          ] }}