GitHub Actions 的工作流程语法

关于工作流程的 YAML 语法

工作流程文件使用 YAML 语法，必须有 .yml 或 .yaml 文件扩展名。 如果您是 YAML 的新用户并想要了解更多信息，请参阅“Y 分钟了解 YAML”。

必须将工作流程文件存储在仓库的 .github/workflows 目录中。

name

工作流程的名称。 GitHub 在仓库的操作页面上显示工作流程的名称。 如果省略 name，GitHub 将其设置为相对于仓库� �目录的工作流程文件路径。

on

To automatically trigger a workflow, use on to define which events can cause the workflow to run. 有关可用事件的列表，请参阅“触发工作流程的事件”。

You can define single or multiple events that can a trigger workflow, or set a time schedule. You can also restrict the execution of a workflow to only occur for specific files, tags, or branch changes. 以下各节介绍了这些选项。

Using a single event

For example, a workflow with the following on value will run when a push is made to any branch in the workflow's repository:

on: push

Using multiple events

You can specify a single event or multiple events. For example, a workflow with the following on value will run when a push is made to any branch in the repository or when someone forks the repository:

on: [push, fork]

If you specify multiple events, only one of those events needs to occur to trigger your workflow. If multiple triggering events for your workflow occur at the same time, multiple workflow runs will be triggered.

Using activity types

Some events have activity types that give you more control over when your workflow should run. Use on.<event_name>.types to define the type of event activity that will trigger a workflow run.

For example, the issue_comment event has the created, edited, and deleted activity types. If your workflow triggers on the label event, it will run whenever a label is created, edited, or deleted. If you specify the created activity type for the label event, your workflow will run when a label is created but not when a label is edited or deleted.

on:
  label:
    types:
      - created

If you specify multiple activity types, only one of those event activity types needs to occur to trigger your workflow. If multiple triggering event activity types for your workflow occur at the same time, multiple workflow runs will be triggered. For example, the following workflow triggers when an issue is opened or labeled. If an issue with two labels is opened, three workflow runs will start: one for the issue opened event and two for the two issue labeled events.

on:
  issue:
    types:
      - opened
      - labeled

有关每个事件及其活动类型的更多信息，请参阅“触发工作流程的事件”。

Using filters

Some events have filters that give you more control over when your workflow should run.

For example, the push event has a branches filter that causes your workflow to run only when a push to a branch that matches the branches filter occurs, instead of when any push occurs.

on:
  push:
    branches:
      - main
      - 'releases/**'

Using activity types and filters with multiple events

If you specify activity types or filters for an event and your workflow triggers on multiple events, you must configure each event separately. You must append a colon (:) to all events, including events without configuration.

For example, a workflow with the following on value will run when:

• A label is created
• A push is made to the main branch in the repository
• A push is made to a GitHub Pages-enabled branch

on:
  label:
    types:
      - created
  push:
    branches:
      - main
  page_build:

on.<event_name>.types

Use on.<event_name>.types to define the type of activity that will trigger a workflow run. 大多数 GitHub 事件由多种活动触发。 For example, the label is triggered when a label is created, edited, or deleted. 通过 types 关键词可缩小触发工作流程运行的活动类型的范围。 如果只有一种活动类型可触发 web 挂钩事件，就没有必要使用 types 关键词。

您可以使用事件 types 的数组。 有关每个事件及其活动类型的更多信息，请参阅“触发工作流程的事件”。

on:
  label:
    types: [created, edited]

on.<pull_request|pull_request_target>.<branches|branches-ignore>

When using the pull_request and pull_request_target events, you can configure a workflow to run only for pull requests that target specific branches.

Use the branches filter when you want to include branch name patterns or when you want to both include and exclude branch names patterns. Use the branches-ignore filter when you only want to exclude branch name patterns. You cannot use both the branches and branches-ignore filters for the same event in a workflow.

If you define both branches/branches-ignore and paths, the workflow will only run when both filters are satisfied.

The branches and branches-ignore keywords accept glob patterns that use characters like *, **, +, ?, ! and others to match more than one branch name. If a name contains any of these characters and you want a literal match, you need to escape each of these special characters with \. 有关 glob 模式的更多信息，请参阅“过滤器模式备忘清单”。

Example: Including branches

The patterns defined in branches are evaluated against the Git ref's name. For example, the following workflow would run whenever there is a pull_request event for a pull request targeting:

• A branch named main (refs/heads/main)
• A branch named mona/octocat (refs/heads/mona/octocat)
• A branch whose name starts with releases/, like releases/10 (refs/heads/releases/10)

on:
  pull_request:
    # Sequence of patterns matched against refs/heads
    branches:    
      - main
      - 'mona/octocat'
      - 'releases/**'

Example: Excluding branches

When a pattern matches the branches-ignore pattern, the workflow will not run. The patterns defined in branches are evaluated against the Git ref's name. For example, the following workflow would run whenever there is a pull_request event unless the pull request is targeting:

• A branch named mona/octocat (refs/heads/mona/octocat)
• A branch whose name matches releases/**-alpha, like beta/3-alpha (refs/releases/beta/3-alpha)

on:
  pull_request:
    # Sequence of patterns matched against refs/heads
    branches-ignore:    
      - 'mona/octocat'
      - 'releases/**-alpha'

Example: Including and excluding branches

You cannot use branches and branches-ignore to filter the same event in a single workflow. If you want to both include and exclude branch patterns for a single event, use the branches filter along with the ! character to indicate which branches should be excluded.

If you define a branch with the ! character, you must also define at least one branch without the ! character. If you only want to exclude branches, use branches-ignore instead.

您定义模式事项的顺序。

• 肯定匹配后的匹配否定模式（前缀为 !）将排除 Git 引用。
• 否定匹配后的匹配肯定模式将再次包含 Git 引用。

The following workflow will run on pull_request events for pull requests that target releases/10 or releases/beta/mona, but for pull requests that target releases/10-alpha or releases/beta/3-alpha because the negative pattern !releases/**-alpha follows the positive pattern.

on:
  pull_request:
    branches:    
      - 'releases/**'
      - '!releases/**-alpha'

on.push.<branches|tags|branches-ignore|tags-ignore>

When using the push event, you can configure a workflow to run on specific branches or tags.

Use the branches filter when you want to include branch name patterns or when you want to both include and exclude branch names patterns. Use the branches-ignore filter when you only want to exclude branch name patterns. You cannot use both the branches and branches-ignore filters for the same event in a workflow.

Use the tags filter when you want to include tag name patterns or when you want to both include and exclude tag names patterns. Use the tags-ignore filter when you only want to exclude tag name patterns. You cannot use both the tags and tags-ignore filters for the same event in a workflow.

If you define only tags/tag-ignore or only branches/branches-ignore, the workflow won't run for events affecting the undefined Git ref. If you define neither tags/tag-ignore or branches/branches-ignore, the workflow will run for events affecting either branches or tags. If you define both branches/branches-ignore and paths, the workflow will only run when both filters are satisfied.

branches、branches-ignore、tags 和 tags-ignore 关键词接受使用 *、**、+、?、! 等字符匹配多个分支或� �记名称的 glob 模式。 If a name contains any of these characters and you want a literal match, you need to escape each of these special characters with \. 有关 glob 模式的更多信息，请参阅“过滤器模式备忘清单”。

示例：包括分支和� �记

在 branches 和 tags 中定义的模式� �据 Git ref 的名称进行评估。 For example, the following workflow would run whenever there is a push event to:

• A branch named main (refs/heads/main)
• A branch named mona/octocat (refs/heads/mona/octocat)
• A branch whose name starts with releases/, like releases/10 (refs/heads/releases/10)
• A tag named v2 (refs/tags/v2)
• A tag whose name starts with v1., like v1.9.1 (refs/tags/v1.9.1)

on:
  push:
    # Sequence of patterns matched against refs/heads
    branches:    
      - main
      - 'mona/octocat'
      - 'releases/**'
    # Sequence of patterns matched against refs/tags
    tags:        
      - v2
      - v1.*

Example: Excluding branches and tags

When a pattern matches the branches-ignore or tags-ignore pattern, the workflow will not run. 在 branches 和 tags 中定义的模式� �据 Git ref 的名称进行评估。 For example, the following workflow would run whenever there is a push event, unless the push event is to:

• A branch named mona/octocat (refs/heads/mona/octocat)
• A branch whose name matches releases/**-alpha, like beta/3-alpha (refs/releases/beta/3-alpha)
• A tag named v2 (refs/tags/v2)
• A tag whose name starts with v1., like v1.9 (refs/tags/v1.9)

on:
  push:
    # Sequence of patterns matched against refs/heads
    branches-ignore:    
      - 'mona/octocat'
      - 'releases/**-alpha'
    # Sequence of patterns matched against refs/tags
    tags-ignore:        
      - v2
      - v1.*

Example: Including and excluding branches and tags

You can't use branches and branches-ignore to filter the same event in a single workflow. Similarly, you can't use tags and tags-ignore to filter the same event in a single workflow. If you want to both include and exclude branch or tag patterns for a single event, use the branches or tags filter along with the ! character to indicate which branches or tags should be excluded.

If you define a branch with the ! character, you must also define at least one branch without the ! character. If you only want to exclude branches, use branches-ignore instead. Similarly, if you define a tag with the ! character, you must also define at least one tag without the ! character. If you only want to exclude tags, use tags-ignore instead.

您定义模式事项的顺序。

• 肯定匹配后的匹配否定模式（前缀为 !）将排除 Git 引用。
• 否定匹配后的匹配肯定模式将再次包含 Git 引用。

以下工作流程将在到 releases/10 或 releases/beta/mona 的推送上运行，而不会在到 releases/10-alpha 或 releases/beta/3-alpha 的推送上运行，� 为否定模式 !releases/**-alpha 后跟肯定模式。

on:
  push:
    branches:
      - 'releases/**'
      - '!releases/**-alpha'

on.<push|pull_request|pull_request_target>.<paths|paths-ignore>

When using the push and pull_request events, you can configure a workflow to run based on what file paths are changed. Path filters are not evaluated for pushes of tags.

Use the paths filter when you want to include file path patterns or when you want to both include and exclude file path patterns. Use the paths-ignore filter when you only want to exclude file path patterns. You cannot use both the paths and paths-ignore filters for the same event in a workflow.

If you define both branches/branches-ignore and paths, the workflow will only run when both filters are satisfied.

The paths and paths-ignore keywords accept glob patterns that use the * and ** wildcard characters to match more than one path name. 更多信息请参阅“过滤器模式备忘清单”。

示例：包括路径

如果至少有一个路径与 paths 过滤器中的模式匹配，工作流程将会运行。 For example, the following workflow would run anytime you push a JavaScript file (.js).

on:
  push:
    paths:
      - '**.js'

Example: Excluding paths

当所有路径名称匹配 paths-ignore 中的模式时，工作流程不会运行。 If any path names do not match patterns in paths-ignore, even if some path names match the patterns, the workflow will run.

具有以下路径过滤器的工作流程仅在 push 事件上运行，这些事件包括至少一个位于仓库� �目录的 docs 目录外的文件。

on:
  push:
    paths-ignore:
      - 'docs/**'

Example: Including and excluding paths

You can not use paths and paths-ignore to filter the same event in a single workflow. If you want to both include and exclude path patterns for a single event, use the paths filter along with the ! character to indicate which paths should be excluded.

If you define a path with the ! character, you must also define at least one path without the ! character. If you only want to exclude paths, use paths-ignore instead.

您定义模式事项的顺序：

• 肯定匹配后的匹配否定模式（前缀为 !）将排除路径。
• 否定匹配后的匹配肯定模式将再次包含路径。

只要 push 事件包括 sub-project 目录或其子目录中的文件，此示例就会运行，除非该文件在 sub-project/docs 目录中。 例如，更改了 sub-project/index.js 或 sub-project/src/index.js 的推送将会触发工作流程运行，但只更改 sub-project/docs/readme.md 的推送不会触发。

on:
  push:
    paths:
      - 'sub-project/**'
      - '!sub-project/docs/**'

Git 差异比较

过滤器决定是否应通过评估已更改文件，并� �据 paths-ignore or paths 列表运行它们，来运行一个工作流程。 如果没有更改文件，工作流程将不会运行。

GitHub 会针对推送使用双点差异，针对拉取请求使用三点差异，生成已更改文件列表：

• 拉取请求： 三点差异比较主题分支的最近版本与其中使用基本分支最新同步主题分支的提交。
• 推送到现有分支： 双点差异可以直接相互比较头部和基础 SHA。
• 推送到新分支：� �据已推送最深提交的前身父项的两点差异。

差异限制为 300 个文件。 如果更改的文件与过滤器返回的前 300 个文件不匹配，工作流程将不会运行。 您可能需要创建更多的特定过滤器，以便工作流程自动运行。

更多信息请参阅“关于比较拉取请求中的分支”。

on.schedule

You can use on.schedule to define a time schedule for your workflows. 您可以使用 POSIX cron 语法安排工作流程在特定的 UTC 时间运行。 预定的工作流程在默认或基础分支的最新提交上运行。 您可以运行预定工作流程的最短间隔是每 5 分钟一次。

此示例在每天 5:30 和 17:30 UTC 触发工作流程：

on:
  schedule:
    # * is a special character in YAML so you have to quote this string
    - cron:  '30 5,17 * * *'

A single workflow can be triggered by multiple schedule events. You can access the schedule event that triggered the workflow through the github.event.schedule context. This example triggers the workflow to run at 5:30 UTC every Monday-Thursday, but skips the Not on Monday or Wednesday step on Monday and Wednesday.

on:
  schedule:
    - cron: '30 5 * * 1,3'
    - cron: '30 5 * * 2,4'

jobs:
  test_schedule:
    runs-on: ubuntu-latest
    steps:
      - name: Not on Monday or Wednesday
        if: github.event.schedule != '30 5 * * 1,3'
        run: echo "This step will be skipped on Monday and Wednesday"
      - name: Every time
        run: echo "This step will always run"

有关计划任务语法的更多信息请参阅“触发工作流程的事件”。

on.workflow_run.<branches|branches-ignore>

When using the workflow_run event, you can specify what branches the triggering workflow must run on in order to trigger your workflow.

The branches and branches-ignore filters accept glob patterns that use characters like *, **, +, ?, ! and others to match more than one branch name. If a name contains any of these characters and you want a literal match, you need to escape each of these special characters with \. 有关 glob 模式的更多信息，请参阅“过滤器模式备忘清单”。

For example, a workflow with the following trigger will only run when the workflow named Build runs on a branch whose name starts with releases/:

on:
  workflow_run:
    workflows: ["Build"]
    types: [requested]
    branches:
      - 'releases/**'

A workflow with the following trigger will only run when the workflow named Build runs on a branch that is not named canary:

on:
  workflow_run:
    workflows: ["Build"]
    types: [requested]
    branches-ignore:
      - "canary"

You cannot use both the branches and branches-ignore filters for the same event in a workflow. If you want to both include and exclude branch patterns for a single event, use the branches filter along with the ! character to indicate which branches should be excluded.

您定义模式事项的顺序。

• A matching negative pattern (prefixed with !) after a positive match will exclude the branch.
• A matching positive pattern after a negative match will include the branch again.

For example, a workflow with the following trigger will run when the workflow named Build runs on a branch that is named releases/10 or releases/beta/mona but will not releases/10-alpha, releases/beta/3-alpha, or main.

on:
  workflow_run:
    workflows: ["Build"]
    types: [requested]
    branches:
      - 'releases/**'
      - '!releases/**-alpha'

on.workflow_dispatch.inputs

When using the workflow_dispatch event, you can optionally specify inputs that are passed to the workflow.

触发的工作流程接收 github.event.input 上下文中的输入。 更多信息请参阅“上下文”。

on:
  workflow_dispatch:
    inputs:
      logLevel:
        description: 'Log level'
        required: true
        default: 'warning' 
      tags:
        description: 'Test scenario tags'
        required: false 

jobs:
  print-tag:
    runs-on: ubuntu-latest

    steps:
      - name: Print the input tag to STDOUT
        run: echo  The tag is ${{ github.event.inputs.tag }} 

env

A map of environment variables that are available to the steps of all jobs in the workflow. You can also set environment variables that are only available to the steps of a single job or to a single step. For more information, see jobs.<job_id>.env and jobs.<job_id>.steps[*].env.

当多个环境变量使用相同的名称定义时，GitHub 会使用最特定的环境变量。 例如，步骤中定义的环境变量在步骤执行时将覆盖名称相同的作业和工作流程变量。 为作业定义的变量在作业执行时将覆盖名称相同的工作流程变量。

示例

env:
  SERVER: production

defaults

Use defaults to create a map of default settings that will apply to all jobs in the workflow. 您也可以设置只可用于作业的默认设置。 更多信息请参阅 jobs.<job_id>.defaults。

使用相同名称定义了多个默认设置时，GitHub 会使用最具体的默认设置。 例如，在作业中定义的默认设置将覆盖在工作流程中定义的同名默认设置。

defaults.run

You can use defaults.run to provide default shell and working-directory options for all run steps in a workflow. 您也可以设置只可用于作业的 run 默认设置。 更多信息请参阅 jobs.<job_id>.defaults.run。 您不能在此关键词中使用上下文或表达式。

使用相同名称定义了多个默认设置时，GitHub 会使用最具体的默认设置。 例如，在作业中定义的默认设置将覆盖在工作流程中定义的同名默认设置。

Example: Set the default shell and working directory

defaults:
  run:
    shell: bash
    working-directory: scripts

jobs

A workflow run is made up of one or more jobs, which run in parallel by default. 要按顺序运行作业，您可以使用 <job_id>needs 关键词在其他作业上定义依赖项。

每个作业在 runs-on 指定的运行器环境中运行。

在工作流程的使用限制之内可运行� 限数量的作业。 For more information, see "Usage limits and billing" for GitHub-hosted runners and "About self-hosted runners" for self-hosted runner usage limits.

If you need to find the unique identifier of a job running in a workflow run, you can use the GitHub Enterprise Server API. 更多信息请参阅“工作流程作业”。

jobs.<job_id>

Use jobs.<job_id> to give your job a unique identifier. 键值 job_id 是一个字符串，其值是作业配置数据的� 像。 必须将 <job_id> 替换为 jobs 对象唯一的字符串。 <job_id> 必须以字母或 _ 开头，并且只能包含字母数字字符、- 或 _。

Example: Creating jobs

In this example, two jobs have been created, and their job_id values are my_first_job and my_second_job.

jobs:
  my_first_job:
    name: My first job
  my_second_job:
    name: My second job

jobs.<job_id>.name

Use jobs.<job_id>.name to a name for the job, which is displayed on GitHub.

jobs.<job_id>.needs

Use jobs.<job_id>.needs to identify any jobs that must complete successfully before this job will run. 它可以是一个字符串，也可以是字符串数组。 如果某个作业失败，则所有需要它的作业都会被跳过，除非这些作业使用让该作业继续的条件表达式。

Example: Requiring successful dependent jobs

jobs:
  job1:
  job2:
    needs: job1
  job3:
    needs: [job1, job2]

在此示例中，job1 必须在 job2 开始之前成功完成，而 job3 要等待 job1 和 job2 完成。

此示例中的作业按顺序运行：

1. job1
2. job2
3. job3

Example: Not requiring successful dependent jobs

jobs:
  job1:
  job2:
    needs: job1
  job3:
    if: ${{ always() }}
    needs: [job1, job2]

在此示例中，job3 使用 always() 条件表达式，� 此它始终在 job1 和 job2 完成后运行，不管它们是否成功。 For more information, see "Expressions."

jobs.<job_id>.if

You can use the jobs.<job_id>.if conditional to prevent a job from running unless a condition is met. 您可以使用任何支持上下文和表达式来创建条件。

在 if 条件下使用表达式时，可以省略表达式语法 (${{ }})，� 为 GitHub 会自动将 if 条件作为表达式求值。 For more information, see "Expressions."

Example: Only run job for specific repository

This example uses if to control when the production-deploy job can run. It will only run if the repository is named octo-repo-prod and is within the octo-org organization. Otherwise, the job will be marked as skipped.

name: example-workflow
on: [push]
jobs:
  production-deploy:
    if: github.repository == 'octo-org/octo-repo-prod'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v2
        with:
          node-version: '14'
      - run: npm install -g bats

jobs.<job_id>.runs-on

Use jobs.<job_id>.runs-on to define the type of machine to run the job on. You can provide runs-on as a single string or as an array of strings. If you specify an array of strings, your workflow will run on a self-hosted runner whose labels match all of the specified runs-on values, if available. If you would like to run your workflow on multiple machines, use jobs.<job_id>.strategy.

Choosing GitHub-hosted runners

如果使用 GitHub 托管的运行器，每个作业将在 runs-on 指定的虚拟环境的新实例中运行。

可用的 GitHub 托管的运行器类型包括：

Example: Specifying an operating system

runs-on: ubuntu-latest

更多信息请参阅“GitHub 托管的运行器的虚拟环境”。

Choosing self-hosted runners

要为工作指定自托管的运行器，请在工作流程文件中使用自托管运行器� �签配置 runs-on。

所有自托管运行器都有 self-hosted � �签。 仅使用此� �签将选择任何自托管运行器。 To select runners that meet certain criteria, such as operating system or architecture, we recommend providing an array of labels that begins with self-hosted (this must be listed first) and then includes additional labels as needed. When you specify an array of labels, jobs will be queued on runners that have all the labels that you specify.

Although the self-hosted label is not required, we strongly recommend specifying it when using self-hosted runners to ensure that your job does not unintentionally specify any current or future GitHub-hosted runners.

Example: Using labels for runner selection

runs-on: [self-hosted, linux]

更多信息请参阅“关于自托管的运行器”和“在工作流程中使用自托管的运行器”。

jobs.<job_id>.outputs

You can use jobs.<job_id>.outputs to create a map of outputs for a job. 作业输出可用于所有依赖此作业的下游作业。 有关定义作业依赖项的更多信息，请参阅 jobs.<job_id>.needs。

作业输出是字符串，当每个作业结束时，在运行器上评估包含表达式的作业输出。 包含密� �的输出在运行器上编辑，不会发送至 GitHub Actions。

要在依赖的作业中使用作业输出, 您可以使用 needs 上下文。 更多信息请参阅“上下文”。

Example: Defining outputs for a job

jobs:
  job1:
    runs-on: ubuntu-latest
    # Map a step output to a job output
    outputs:
      output1: ${{ steps.step1.outputs.test }}
      output2: ${{ steps.step2.outputs.test }}
    steps:
      - id: step1
        run: echo "::set-output name=test::hello"
      - id: step2
        run: echo "::set-output name=test::world"
  job2:
    runs-on: ubuntu-latest
    needs: job1
    steps:
      - run: echo ${{needs.job1.outputs.output1}} ${{needs.job1.outputs.output2}}

jobs.<job_id>.env

A map of environment variables that are available to all steps in the job. You can also set environment variables for the entire workflow or an individual step. For more information, see env and jobs.<job_id>.steps[*].env.

当多个环境变量使用相同的名称定义时，GitHub 会使用最特定的环境变量。 例如，步骤中定义的环境变量在步骤执行时将覆盖名称相同的作业和工作流程变量。 为作业定义的变量在作业执行时将覆盖名称相同的工作流程变量。

示例

jobs:
  job1:
    env:
      FIRST_NAME: Mona

jobs.<job_id>.defaults

Use jobs.<job_id>.defaults to create a map of default settings that will apply to all steps in the job. 您也可以设置整个工作流程的默认设置。 For more information, see defaults.

使用相同名称定义了多个默认设置时，GitHub 会使用最具体的默认设置。 例如，在作业中定义的默认设置将覆盖在工作流程中定义的同名默认设置。

jobs.<job_id>.defaults.run

Use jobs.<job_id>.defaults.run to provide default shell and working-directory to all run steps in the job. 此部分不允许上下文和表达式。

您可以为作业中的所有 run 步骤提供默认的 shell 和 working-directory 选项。 您也可以为整个工作流程设置 run 的默认设置。 更多信息请参阅 jobs.defaults.run。 您不能在此关键词中使用上下文或表达式。

使用相同名称定义了多个默认设置时，GitHub 会使用最具体的默认设置。 例如，在作业中定义的默认设置将覆盖在工作流程中定义的同名默认设置。

Example: Setting default run step options for a job

jobs:
  job1:
    runs-on: ubuntu-latest
    defaults:
      run:
        shell: bash
        working-directory: scripts

jobs.<job_id>.steps

A job contains a sequence of tasks called steps. Steps can run commands, run setup tasks, or run an action in your repository, a public repository, or an action published in a Docker registry. Not all steps run actions, but all actions run as a step. Each step runs in its own process in the runner environment and has access to the workspace and filesystem. Because steps run in their own process, changes to environment variables are not preserved between steps. GitHub provides built-in steps to set up and complete a job.

You can run an unlimited number of steps as long as you are within the workflow usage limits. For more information, see "Usage limits and billing" for GitHub-hosted runners and "About self-hosted runners" for self-hosted runner usage limits.

示例

name: Greeting from Mona

on: push

jobs:
  my-job:
    name: My Job
    runs-on: ubuntu-latest
    steps:
      - name: Print a greeting
        env:
          MY_VAR: Hi there! My name is
          FIRST_NAME: Mona
          MIDDLE_NAME: The
          LAST_NAME: Octocat
        run: |
          echo $MY_VAR $FIRST_NAME $MIDDLE_NAME $LAST_NAME.

jobs.<job_id>.steps[*].id

A unique identifier for the step. 您可以使用 id 引用上下文中的步骤。 更多信息请参阅“上下文”。

jobs.<job_id>.steps[*].if

You can use the if conditional to prevent a step from running unless a condition is met. 您可以使用任何支持上下文和表达式来创建条件。

在 if 条件下使用表达式时，可以省略表达式语法 (${{ }})，� 为 GitHub 会自动将 if 条件作为表达式求值。 For more information, see "Expressions."

示例：使用上下文

此步骤仅在事件类型为 pull_request 并且事件操作为 unassigned 时运行。

steps:
 - name: My first step
   if: ${{ github.event_name == 'pull_request' && github.event.action == 'unassigned' }}
   run: echo This event is a pull request that had an assignee removed.

示例：使用状态检查功能

The my backup step only runs when the previous step of a job fails. For more information, see "Expressions."

steps:
  - name: My first step
    uses: octo-org/action-name@main
  - name: My backup step
    if: ${{ failure() }}
    uses: actions/heroku@1.0.0

jobs.<job_id>.steps[*].name

A name for your step to display on GitHub.

jobs.<job_id>.steps[*].uses

Selects an action to run as part of a step in your job. 操作是一种可重复使用的代� �单位。 您可以使用工作流程所在仓库中、公共仓库中或发布 Docker 容器� 像中定义的操作。

强烈建议指定 Git ref、SHA 或 Docker � �记编号来包含所用操作的版本。 如果不指定版本，在操作所有者发布更新时可能会中断您的工作流程或� 成非预期的行为。

• 使用已发行操作版本的 SHA 对于稳定性和安全性是最安全的。
• 使用特定主要操作版本可在保持兼容性的同时接收关键修复和安全补丁。 还可确保您的工作流程继续工作。
• 使用操作的默认分支可能很方便，但如果有人新发布具有突� �性更改的主要版本，您的工作流程可能会中断。

Some actions require inputs that you must set using the with keyword. 请查阅操作的自述文件，确定所需的输入。

Actions are either JavaScript files or Docker containers. If the action you're using is a Docker container you must run the job in a Linux environment. For more details, see runs-on.

示例：使用版本化操作

steps:
  # Reference a specific commit
  - uses: actions/checkout@a81bbbf8298c0fa03ea29cdc473d45769f953675
  # Reference the major version of a release
  - uses: actions/checkout@v2
  # Reference a specific version
  - uses: actions/checkout@v2.2.0
  # Reference a branch
  - uses: actions/checkout@main

示例：使用公共操作

{owner}/{repo}@{ref}

You can specify a branch, ref, or SHA in a public GitHub repository.

jobs:
  my_first_job:
    steps:
      - name: My first step
        # Uses the default branch of a public repository
        uses: actions/heroku@main
      - name: My second step
        # Uses a specific version tag of a public repository
        uses: actions/aws@v2.0.1

示例：在子目录中使用公共操作

{owner}/{repo}/{path}@{ref}

A subdirectory in a public GitHub repository at a specific branch, ref, or SHA.

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: actions/aws/ec2@main

示例：使用工作流程所在仓库中操作

./path/to/dir

The path to the directory that contains the action in your workflow's repository. You must check out your repository before using the action.

jobs:
  my_first_job:
    steps:
      - name: Check out repository
        uses: actions/checkout@v2
      - name: Use local my-action
        uses: ./.github/actions/my-action

示例：使用 Docker 中枢操作

docker://{image}:{tag}

A Docker image published on Docker Hub.

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: docker://alpine:3.8

示例：使用 Docker 公共注册表操作

docker://{host}/{image}:{tag}

A Docker image in a public registry. This example uses the Google Container Registry at gcr.io.

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: docker://gcr.io/cloud-builders/gradle

示例：在不同于工作流程的私有仓库中使用操作

Your workflow must checkout the private repository and reference the action locally. Generate a personal access token and add the token as an encrypted secret. 更多信息请参阅“创建个人访问令牌”和“� 密密� �”。

Replace PERSONAL_ACCESS_TOKEN in the example with the name of your secret.

jobs:
  my_first_job:
    steps:
      - name: Check out repository
        uses: actions/checkout@v2
        with:
          repository: octocat/my-private-repo
          ref: v1.0
          token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
          path: ./.github/actions/my-private-repo
      - name: Run my action
        uses: ./.github/actions/my-private-repo/my-action

jobs.<job_id>.steps[*].run

Runs command-line programs using the operating system's shell. If you do not provide a name, the step name will default to the text specified in the run command.

Commands run using non-login shells by default. You can choose a different shell and customize the shell used to run commands. For more information, see jobs.<job_id>.steps[*].shell.

Each run keyword represents a new process and shell in the runner environment. When you provide multi-line commands, each line runs in the same shell. 例如：

• 单行命令：

  - name: Install Dependencies
    run: npm install
  

• 多行命令：

  - name: Clean install dependencies and build
    run: |
      npm ci
      npm run build
  

Using the working-directory keyword, you can specify the working directory of where to run the command.

- name: Clean temp directory
  run: rm -rf *
  working-directory: ./temp

jobs.<job_id>.steps[*].shell

You can override the default shell settings in the runner's operating system using the shell keyword. You can use built-in shell keywords, or you can define a custom set of shell options. The shell command that is run internally executes a temporary file that contains the commands specified in the run keyword.

示例：使用 bash 运行脚本

steps:
  - name: Display the path
    run: echo $PATH
    shell: bash

示例：使用 Windows cmd 运行脚本

steps:
  - name: Display the path
    run: echo %PATH%
    shell: cmd

示例：使用 PowerShell Core 运行脚本

steps:
  - name: Display the path
    run: echo ${env:PATH}
    shell: pwsh

示例：使用 PowerShell 桌面运行脚本

steps:
  - name: Display the path
    run: echo ${env:PATH}
    shell: powershell

示例：运行 python 脚本

steps:
  - name: Display the path
    run: |
      import os
      print(os.environ['PATH'])
    shell: python

自定义 shell

You can set the shell value to a template string using command […options] {0} [..more_options]. GitHub interprets the first whitespace-delimited word of the string as the command, and inserts the file name for the temporary script at {0}.

例如：

steps:
  - name: Display the environment variables and their values
    run: |
      print %ENV
    shell: perl {0}

The command used, perl in this example, must be installed on the runner.

退出代� �和错误操作首选项

For built-in shell keywords, we provide the following defaults that are executed by GitHub-hosted runners. You should use these guidelines when running shell scripts.

• bash/sh：

  • 使用 set -eo pipefail 的快速失败行为：bash 和内置 shell 的默认值。 它还是未在非 Windows 平台上提供选项时的默认值。
  • 您可以向 shell 选项提供模板字符串，以退出快速失败并接管全面控制权。 例如 bash {0}。
  • sh 类 shell 使用脚本中最后执行的命令的退出代� �退出，也是操作的默认行为。 运行程序将� �据此退出代� �将步骤的状态报告为失败/成功。

• powershell/pwsh

  • 可能时的快速失败行为。 对于 pwsh 和 powershell 内置 shell，我们将 $ErrorActionPreference = 'stop' 附� 到脚本内容。
  • 我们将 if ((Test-Path -LiteralPath variable:\LASTEXITCODE)) { exit $LASTEXITCODE } 附� 到 powershell 脚本，以使操作状态反� 脚本的最后一个退出代� �。
  • 用户可随时通过不使用内置 shell 并提供类似如下的自定义 shell 选项来退出：pwsh -File {0} 或 powershell -Command "& '{0}'"，具体取决于需求。

• cmd

  • 除了编写脚本来检查每个错误代� �并相应地响应之外，似乎没有办法完全选择快速失败行为。 由于我们默认不能实际提供该行为，� 此您需要将此行为写入脚本。
  • cmd.exe 在退出时带有其执行的最后一个程序的错误等级，并且会将错误代� �返回到运行程序。 此行为在内部与上一个 sh 和 pwsh 默认行为一致，是 cmd.exe 的默认值，所以此行为保持不变。

jobs.<job_id>.steps[*].with

A map of the input parameters defined by the action. 每个输入参数都是一个键/值对。 输入参数被设置为环境变量。 The variable is prefixed with INPUT_ and converted to upper case.

示例

Defines the three input parameters (first_name, middle_name, and last_name) defined by the hello_world action. These input variables will be accessible to the hello-world action as INPUT_FIRST_NAME, INPUT_MIDDLE_NAME, and INPUT_LAST_NAME environment variables.

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: actions/hello_world@main
        with:
          first_name: Mona
          middle_name: The
          last_name: Octocat

jobs.<job_id>.steps[*].with.args

A string that defines the inputs for a Docker container. GitHub 在容器启动时将 args � 递到容器的 ENTRYPOINT。 An array of strings is not supported by this parameter.

示例

steps:
  - name: Explain why this job ran
    uses: octo-org/action-name@main
    with:
      entrypoint: /bin/echo
      args: The ${{ github.event_name }} event triggered this step.

args 用来代替 Dockerfile 中的 CMD 指令。 如果在 Dockerfile 中使用 CMD，请遵循按偏好顺序排序的指导方针：

1. 在操作的自述文件中记录必要的参数，并在 CMD 指令的中忽略它们。
2. 使用默认值，允许不指定任何 args 即可使用操作。
3. 如果操作显示 --help � �记或类似项，请将其用作默认值，以便操作自行记录。

jobs.<job_id>.steps[*].with.entrypoint

Overrides the Docker ENTRYPOINT in the Dockerfile, or sets it if one wasn't already specified. Unlike the Docker ENTRYPOINT instruction which has a shell and exec form, entrypoint keyword accepts only a single string defining the executable to be run.

示例

steps:
  - name: Run a custom command
    uses: octo-org/action-name@main
    with:
      entrypoint: /a/different/executable

The entrypoint keyword is meant to be used with Docker container actions, but you can also use it with JavaScript actions that don't define any inputs.

jobs.<job_id>.steps[*].env

Sets environment variables for steps to use in the runner environment. You can also set environment variables for the entire workflow or a job. For more information, see env and jobs.<job_id>.env.

当多个环境变量使用相同的名称定义时，GitHub 会使用最特定的环境变量。 例如，步骤中定义的环境变量在步骤执行时将覆盖名称相同的作业和工作流程变量。 为作业定义的变量在作业执行时将覆盖名称相同的工作流程变量。

Public actions may specify expected environment variables in the README file. If you are setting a secret in an environment variable, you must set secrets using the secrets context. For more information, see "Using environment variables" and "Contexts."

示例

steps:
  - name: My first action
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      FIRST_NAME: Mona
      LAST_NAME: Octocat

jobs.<job_id>.steps[*].continue-on-error

Prevents a job from failing when a step fails. Set to true to allow a job to pass when this step fails.

jobs.<job_id>.steps[*].timeout-minutes

The maximum number of minutes to run the step before killing the process.

jobs.<job_id>.timeout-minutes

The maximum number of minutes to let a job run before GitHub automatically cancels it. Default: 360

If the timeout exceeds the job execution time limit for the runner, the job will be canceled when the execution time limit is met instead. For more information about job execution time limits, see "Usage limits and billing" for GitHub-hosted runners and "About self-hosted runners" for self-hosted runner usage limits.

jobs.<job_id>.strategy

Use jobs.<job_id>.strategy to create a build matrix for your jobs. 您可以定义要在其中运行每项作业的不同变种。

jobs.<job_id>.strategy.matrix

Use jobs.<job_id>.strategy.matrix to define a matrix of different job configurations. 矩阵允许您通过在单个作业定义中执行变量替换来创建多个作业。 例如，可以使用矩阵为多个受支持的编程语言、操作系统或工具版本创建作业。 矩阵重新使用作业的配置，并为您配置的每个矩阵创建作业。

作业矩阵在每次工作流程运行时最多可生成 256 个作业。 此限制也适用于自托管运行器。

您在 matrix 中定义的每个选项都有键和值。 定义的键将成为 matrix 上下文中的属性，您可以在工作流程文件的其他区域中引用该属性。 例如，如果定义包含操作系统数组的键 os，您可以使用 matrix.os 属性作为 runs-on 关键字的值，为每个操作系统创建一个作业。 更多信息请参阅“上下文”。

定义 matrix 事项的顺序。 定义的第一个选项将是工作流程中运行的第一个作业。

示例：运行多个版本的 Node.js

您可以提供配置选项阵列来指定矩阵。 例如，如果运行器支持 Node.js 版本 10、12 和 14，则您可以在 matrix 中指定这些版本的阵列。

此示例通过设置三个 Node.js 版本阵列的 node 键创建三个作业的矩阵。 为使用矩阵，示例将 matrix.node 上下文属性设置为 setup-node 操作的输入参数 node-version。 � 此，将有三个作业运行，每个使用不同的 Node.js 版本。

strategy:
  matrix:
    node: [10, 12, 14]
steps:
  # Configures the node version used on GitHub-hosted runners
  - uses: actions/setup-node@v2
    with:
      # The Node.js version to configure
      node-version: ${{ matrix.node }}

setup-node 操作是在使用 GitHub 托管的运行器时建议用于配置 Node.js 版本的方式。 更多信息请参阅 setup-node 操作。

示例：使用多个操作系统运行

您可以创建矩阵以在多个运行器操作系统上运行工作流程。 您也可以指定多个矩阵配置。 此示例创建包含 6 个作业的矩阵：

• 在 os 阵列中指定了 2 个操作系统
• 在 node 阵列中指定了 3 个 Node.js 版本

定义操作系统矩阵时，必须将 runs-on 的值设置为您定义的 matrix.os 上下文属性。

runs-on: ${{ matrix.os }}
strategy:
  matrix:
    os: [ubuntu-18.04, ubuntu-20.04]
    node: [10, 12, 14]
steps:
  - uses: actions/setup-node@v2
    with:
      node-version: ${{ matrix.node }}

要查找 GitHub 托管的运行器支持的配置选项，请参阅“GitHub 托管的运行器的虚拟环境”。

Example: Including additional values in combinations

您可以将额外的配置选项添� 到已经存在的构建矩阵作业中。 例如，如果要在作业使用 windows-latest 和 node 的版本 8 运行时使用 npm 的特定版本，您可以使用 include 指定该附� 选项。

runs-on: ${{ matrix.os }}
strategy:
  matrix:
    os: [macos-latest, windows-latest, ubuntu-18.04]
    node: [8, 10, 12, 14]
    include:
      # includes a new variable of npm with a value of 6
      # for the matrix leg matching the os and version
      - os: windows-latest
        node: 8
        npm: 6

示例：包括新组合

您可以使用 include 将新作业添� 到构建矩阵中。 任何不匹配包含配置都会添� 到矩阵中。 例如，如果您想要使用 node 版本 14 在多个操作系统上构建，但在 Ubuntu 上需要一个使用节点版本 15 的额外实验性作业，则可使用 include 指定该额外作业。

runs-on: ${{ matrix.os }}
strategy:
  matrix:
    node: [14]
    os: [macos-latest, windows-latest, ubuntu-18.04]
    include:
      - node: 15
        os: ubuntu-18.04
        experimental: true

示例：从矩阵中排除配置

您可以使用 exclude 选项� 除构建矩阵中定义的特定配置。 使用 exclude � 除由构建矩阵定义的作业。 作业数量是您提供的数组中所包括的操作系统 (os) 数量减去所有减项 (exclude) 后的叉积。

runs-on: ${{ matrix.os }}
strategy:
  matrix:
    os: [macos-latest, windows-latest, ubuntu-18.04]
    node: [8, 10, 12, 14]
    exclude:
      # excludes node 8 on macOS
      - os: macos-latest
        node: 8

在矩阵中使用环境变量

您可以使用 include 键为每个测试组合添� 自定义环境变量。 然后，您可以在后面的步骤中引用自定义环境变量。

在此示例中， node-version 的矩阵条目每个都被配置为对 site 和 datacenter 环境变量使用不同的值。 Echo site details 步骤然后使用 env: ${{ matrix.env }} 引用自定义变量：

name: Node.js CI
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      matrix:
       include:
         - node-version: 10.x
           site: "prod"
           datacenter: "site-a"
         - node-version: 12.x
           site: "dev"
           datacenter: "site-b"
    steps:
      - name: Echo site details
        env:
          SITE: ${{ matrix.site }}
          DATACENTER: ${{ matrix.datacenter }}
        run: echo $SITE $DATACENTER

jobs.<job_id>.strategy.fail-fast

When jobs.<job_id>.strategy.fail-fast is set to true, GitHub cancels all in-progress jobs if any matrix job fails. 默认值：true

jobs.<job_id>.strategy.max-parallel

Use jobs.<job_id>.strategy.max-parallel to set the maximum number of jobs that can run simultaneously when using a matrix job strategy. 默认情况下，GitHub 将最大化并发运行的作业数量，具体取决于 GitHub 托管虚拟机上可用的运行程序。

strategy:
  max-parallel: 2

jobs.<job_id>.continue-on-error

Prevents a workflow run from failing when a job fails. Set to true to allow a workflow run to pass when this job fails.

示例：防止特定失败的矩阵作业� 法运行工作流程

You can allow specific jobs in a job matrix to fail without failing the workflow run. For example, if you wanted to only allow an experimental job with node set to 15 to fail without failing the workflow run.

runs-on: ${{ matrix.os }}
continue-on-error: ${{ matrix.experimental }}
strategy:
  fail-fast: false
  matrix:
    node: [13, 14]
    os: [macos-latest, ubuntu-18.04]
    experimental: [false]
    include:
      - node: 15
        os: ubuntu-18.04
        experimental: true

jobs.<job_id>.container

Use jobs.<job_id>.container to create a container to run any steps in a job that don't already specify a container. 如有步骤同时使用脚本和容器操作，则容器操作将运行为同一网络上使用相同卷挂载的同级容器。

若不设置 container，所有步骤将直接在 runs-on 指定的主机上运行，除非步骤引用已配置为在容器中运行的操作。

Example: Running a job within a container

jobs:
  my_job:
    container:
      image: node:14.16
      env:
        NODE_ENV: development
      ports:
        - 80
      volumes:
        - my_docker_volume:/volume_mount
      options: --cpus 1

只指定容器� 像时，可以忽略 image 关键词。

jobs:
  my_job:
    container: node:14.16

jobs.<job_id>.container.image

Use jobs.<job_id>.container.image to define the Docker image to use as the container to run the action. The value can be the Docker Hub image name or a registry name.

jobs.<job_id>.container.credentials

If the image's container registry requires authentication to pull the image, you can use jobs.<job_id>.container.credentials to set a map of the username and password. 凭据与您提供给 Docker 登录 命令的值相同。

Example: Defining credentials for a container registry

container:
  image: ghcr.io/owner/image
  credentials:
     username: ${{ github.actor }}
     password: ${{ secrets.github_token }}

jobs.<job_id>.container.env

Use jobs.<job_id>.container.env to set a map of environment variables in the container.

jobs.<job_id>.container.ports

Use jobs.<job_id>.container.ports to set an array of ports to expose on the container.

jobs.<job_id>.container.volumes

Use jobs.<job_id>.container.volumes to set an array of volumes for the container to use. 您可以使用卷分享作业中服务或其他步骤之间的数据。 可以指定命名的 Docker 卷、匿名的 Docker 卷或主机上的绑定挂载。

要指定卷，需指定来源和目� �路径：

<source>:<destinationPath>.

<source> 是主机上的卷名称或绝对路径，<destinationPath> 是容器中的绝对路径。

Example: Mounting volumes in a container

volumes:
  - my_docker_volume:/volume_mount
  - /data/my_data
  - /source/directory:/destination/directory

jobs.<job_id>.container.options

Use jobs.<job_id>.container.options to configure additional Docker container resource options. 有关选项列表，请参阅“docker create options”。

jobs.<job_id>.services

Used to host service containers for a job in a workflow. Service containers are useful for creating databases or cache services like Redis. The runner automatically creates a Docker network and manages the life cycle of the service containers.

If you configure your job to run in a container, or your step uses container actions, you don't need to map ports to access the service or action. Docker automatically exposes all ports between containers on the same Docker user-defined bridge network. You can directly reference the service container by its hostname. The hostname is automatically mapped to the label name you configure for the service in the workflow.

If you configure the job to run directly on the runner machine and your step doesn't use a container action, you must map any required Docker service container ports to the Docker host (the runner machine). You can access the service container using localhost and the mapped port.

For more information about the differences between networking service containers, see "About service containers."

示例：使用 localhost

This example creates two services: nginx and redis. 指定 Docker 主机端口但不指定容器端口时，容器端口将随机分配给空闲端口。 GitHub sets the assigned container port in the ${{job.services.<service_name>.ports}} context. In this example, you can access the service container ports using the ${{ job.services.nginx.ports['8080'] }} and ${{ job.services.redis.ports['6379'] }} contexts.

services:
  nginx:
    image: nginx
    # Map port 8080 on the Docker host to port 80 on the nginx container
    ports:
      - 8080:80
  redis:
    image: redis
    # Map TCP port 6379 on Docker host to a random free port on the Redis container
    ports:
      - 6379/tcp

jobs.<job_id>.services.<service_id>.image

The Docker image to use as the service container to run the action. The value can be the Docker Hub image name or a registry name.

jobs.<job_id>.services.<service_id>.credentials

If the image's container registry requires authentication to pull the image, you can use jobs.<job_id>.container.credentials to set a map of the username and password. 凭据与您提供给 Docker 登录 命令的值相同。

示例

services:
  myservice1:
    image: ghcr.io/owner/myservice1
    credentials:
      username: ${{ github.actor }}
      password: ${{ secrets.github_token }}
  myservice2:
    image: dockerhub_org/myservice2
    credentials:
      username: ${{ secrets.DOCKER_USER }}
      password: ${{ secrets.DOCKER_PASSWORD }}

jobs.<job_id>.services.<service_id>.env

Sets a map of environment variables in the service container.

jobs.<job_id>.services.<service_id>.ports

Sets an array of ports to expose on the service container.

jobs.<job_id>.services.<service_id>.volumes

Sets an array of volumes for the service container to use. 您可以使用卷分享作业中服务或其他步骤之间的数据。 可以指定命名的 Docker 卷、匿名的 Docker 卷或主机上的绑定挂载。

要指定卷，需指定来源和目� �路径：

<source>:<destinationPath>.

<source> 是主机上的卷名称或绝对路径，<destinationPath> 是容器中的绝对路径。

示例

volumes:
  - my_docker_volume:/volume_mount
  - /data/my_data
  - /source/directory:/destination/directory

jobs.<job_id>.services.<service_id>.options

Additional Docker container resource options. 有关选项列表，请参阅“docker create options”。

过滤器模式备忘清单

You can use special characters in path, branch, and tag filters.

• *： 匹配零个或多个字符，但不匹配 / 字符。 例如，Octo* 匹配 Octocat。
• **： 匹配零个或多个任何字符。
• ?：匹配零个或一个前缀字符。
• +: 匹配一个或多个前置字符。
• [] 匹配列在括号中或包含在范围内的一个字符。 范围只能包含 a-z、A-Z 和 0-9。 例如，范围 [0-9a-z] 匹配任何数字或小写字母。 例如，[CB]at 匹配 Cat 或 Bat，[1-2]00 匹配 100 和 200。
• !：在模式开始时，它将否定以前的正模式。 如果不是第一个字符，它就没有特殊的意义。

The characters *, [, and ! are special characters in YAML. If you start a pattern with *, [, or !, you must enclose the pattern in quotes.

# Valid
- '**/README.md'

# Invalid - creates a parse error that
# prevents your workflow from running.
- **/README.md

For more information about branch, tag, and path filter syntax, see "on.<push>.<branches|tags>", "on.<pull_request>.<branches|tags>", and "on.<push|pull_request>.paths."

匹配分支和� �记的模式

匹配文件路径的模式

Path patterns must match the whole path, and start from the repository's root.