ドキュメントには頻繁に更新が加えられ、その都度公開されています。本ページの翻訳はまだ未完成な部分があることをご了承ください。最新の情報については、英語のドキュメンテーションをご参照ください。本ページの翻訳に問題がある場合はこちらまでご連絡ください。

Contexts and expression syntax for GitHub Actions

You can access context information and evaluate expressions in workflows and actions.

GitHub Actionsは現在、限定パブリックベータとして利用可能で、変更となる可能性があります。ベータ期間中は、高価なワークフローやコンテンツにこの機能を利用することは避けてください。

詳細は「GitHub Actionsについて」(/articles/about-github-actions) を参照してください。

In this article

About context and expressions

You can use expressions to programmatically set variables in workflow files and access contexts. An expression can be any combination of literal values, references to a context, or functions. You can combine literals, context references, and functions using operators.

Expressions are commonly used with the conditional if keyword in a workflow file to determine whether step should run. When an if conditional is true, the step will run.

When you use expressions in an if conditional, you do not need to use the $ syntax because GitHub automatically evaluates the if conditional as an expression. For more information about if conditionals, see "Workflow syntax for GitHub Actions."

Example expression in an if conditional

steps:
- uses: actions/hello-world-javascript-action@master
  if: <expression>

Example setting an environment variable

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

You need to use specific syntax to tell GitHub to evaluate an expression rather than treat it as a string.

${{ <expression> }}

Contexts

Contexts are a way to access information about a workflow run, virtual environment, jobs, and steps. Contexts use the expression syntax.

${{ <context> }}

Context name Description
github Contains information about the workflow run.
job Information about the currently executing job.
steps Information about the currently executing step.
runner Includes information about the runner that is running the current job.
secrets Enables access to secrets set in a repository.

As part of an expression, you may access context information using one of two syntaxes.

In order to use property dereference syntax, the property name must:

Example printing context information to the log file

To inspect the information that is accessible in each context, you can use this workflow file example.

.github/workflows/main.yml

on: push

jobs:
  one:
    runs-on: ubuntu-16.04
    steps:

      - name: Dump GitHub context
        env:
          GITHUB_CONTEXT: ${{ toJson(github) }}
        run: echo "$GITHUB_CONTEXT"
      - name: Dump strategy context
        env:
          STRATEGY_CONTEXT: ${{ toJson(strategy) }}
        run: echo "$STRATEGY_CONTEXT"
      - name: Dump matrix context
        env:
          MATRIX_CONTEXT: ${{ toJson(matrix) }}
        run: echo "$MATRIX_CONTEXT"
      - name: Dump job context
        env:
          JOB_CONTEXT: ${{ toJson(job) }}
        run: echo "$JOB_CONTEXT"
      - name: Dump runner context
        env:
          RUNNER_CONTEXT: ${{ toJson(runner) }}
        run: echo "$RUNNER_CONTEXT"
      - name: Dump steps context
        env:
          STEPS_CONTEXT: ${{ toJson(steps) }}
        run: echo "$STEPS_CONTEXT"

Literals

As part of an expression, you can use boolean, null, number, or string data types. Boolean literals are not case sensitive, so you can use true or True.

Data type Literal value
boolean true or false
null null
number Any number format supported by JSON.
string You must use single quotes. Escape literal single-quotes with a single quote.

Example

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

演算子

演算子 説明
( ) Logical grouping
[ ] インデックス
. Property dereference
! Not
< Less than
<= Less than or equal
> Greater than
>= Greater than or equal
== Equal
!= Not equal
&& And
|| Or

GitHub performs loose equality comparisons.

GitHub uses casts a data type to a number using these conversions.

Type Result
Null 0
Boolean true returns 1
false returns 0
String Parsed from any legal JSON number format, otherwise NaN.
Note, empty string returns 0.
Array NaN
Object NaN

Functions

GitHub offers a set of built-in functions that you can use in expressions. Some functions cast values to a string to perform comparisons.

GitHub uses casts a data type to a string using these conversions.

Type Result
Null ''
Boolean 'true' or 'false'
Number Decimal format, exponential for large numbers
Array Arrays are not converted to a string
Object Objects are not converted to a string

contains

contains( searchString, searchValue )

Returns true if the searchString contains searchValue. If searchString is an array, this function returns true if the searchValue is an element in the array. This function is not case sensitive. Casts values to a string.

Example

contains('Hello world', 'llo') returns true

startsWith

startsWith( searchString, searchValue )

Returns true when searchString starts with searchValue. This function is not case sensitive. Casts values to a string.

Example

startsWith('Hello world', 'He') returns true

endsWith

endsWith( searchString, searchValue )

Returns true if searchString ends with searchValue. This function is not case sensitive. Casts values to a string.

Example

endsWith('Hello world', 'ld') returns true

format

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

Replaces values in the string, with the variable replaceValueN. Variables in the string are specified using the {N} syntax, where N is an integer. You must specify at least one replaceValue and string. There is no maximum for the number of variables (replaceValueN) you can use. Escape curly braces useing double braces.

Example

Returns 'Hello Mona the Octocat'

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

Example escaping braces

Returns '{Hello Mona the Octocat}'

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

join

join( element, optionalElem )

The value for element can be an array or string. All values in element are concatenated into a string. If you provide optionalElem, the value is appended to the end of element. Casts values to a string.

Example using array

join(['Hello', 'Mona', 'the'], 'Octocat') returns 'Hello Mona the Octocat'

Example using string

join('Hello', 'world!') returns 'Hello world!'

toJson

toJSON(value)

Returns a pretty-print JSON representation of value. You can use this function to debug the information provided in contexts.

Example

toJSON(job) might return { "status": "Success" }

Status check functions

You can use the following status check functions as expressions in if conditionals. If your if expression does not contain any of the status functions it will automatically result with success(). For more information about if conditionals, see "Workflow syntax for GitHub Actions."

always

Forces a conditional to evaluate as true, even when canceled. A job or step will not run when a critical failure prevents the task from running. For example, if getting sources failed.

Example
if: always

cancelled

Returns true if the workflow was canceled.

Example
if: cancelled

failure

Returns true when the previous step of a job fails.

Example
steps:
name: my first step
if: failure
Example using step id
steps:
name: my first step
if: job.steps.<step id>.status == failure

success

Returns true when the previous step of a job succeeds.

Example
steps:
name: my first step
if: success
Example using step id
steps:
name: my first step
if: job.steps.<step id>.status == success

Object filters

You can use the * syntax to apply a filter and select matching items in a collection.

For example, consider an array of objects named fruits.

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

The filter fruits.*.name returns the array [ "apple", "orange", "pear" ]

担当者にお尋ねください

探しているものが見つからなかったでしょうか?

弊社にお問い合わせください