diff --git a/content/actions/automating-builds-and-tests/building-and-testing-swift.md b/content/actions/automating-builds-and-tests/building-and-testing-swift.md index 9924803df17c..b40251f2997c 100644 --- a/content/actions/automating-builds-and-tests/building-and-testing-swift.md +++ b/content/actions/automating-builds-and-tests/building-and-testing-swift.md @@ -65,7 +65,7 @@ The examples below demonstrate using the `fwal/setup-swift` action. ### Using multiple Swift versions -You can configure your job to use a multiple versions of Swift in a build matrix. +You can configure your job to use multiple versions of Swift in a matrix. ```yaml{:copy} {% data reusables.actions.actions-not-certified-by-github-comment %} diff --git a/content/actions/learn-github-actions/contexts.md b/content/actions/learn-github-actions/contexts.md index 34914d02d6b1..7b037652c38d 100644 --- a/content/actions/learn-github-actions/contexts.md +++ b/content/actions/learn-github-actions/contexts.md @@ -23,7 +23,7 @@ miniTocMaxHeadingLevel: 3 Contexts are a way to access information about workflow runs, runner environments, jobs, and steps. Each context is an object that contains properties, which can be strings or other objects. -{% data reusables.actions.context-contents %} For example, the `matrix` context is only populated for jobs in a [build matrix](/actions/learn-github-actions/workflow-syntax-for-github-actions#jobsjob_idstrategymatrix). +{% data reusables.actions.context-contents %} For example, the `matrix` context is only populated for jobs in a [matrix](/actions/learn-github-actions/workflow-syntax-for-github-actions#jobsjob_idstrategymatrix). You can access contexts using the expression syntax. For more information, see "[Expressions](/actions/learn-github-actions/expressions)." @@ -552,19 +552,19 @@ The following example contents of the `secrets` context shows the automatic `GIT ## `strategy` context -For workflows with a build matrix, the `strategy` context contains information about the matrix execution strategy for the current job. +For workflows with a matrix, the `strategy` context contains information about the matrix execution strategy for the current job. | Property name | Type | Description | |---------------|------|-------------| | `strategy` | `object` | This context changes for each job in a workflow run. You can access this context from any job or step in a workflow. This object contains all the properties listed below. | -| `strategy.fail-fast` | `string` | When `true`, all in-progress jobs are canceled if any job in a build matrix fails. For more information, see "[Workflow syntax for {% data variables.product.prodname_actions %}](/actions/learn-github-actions/workflow-syntax-for-github-actions#jobsjob_idstrategyfail-fast)." | -| `strategy.job-index` | `string` | The index of the current job in the build matrix. **Note:** This number is a zero-based number. The first job's index in the build matrix is `0`. | -| `strategy.job-total` | `string` | The total number of jobs in the build matrix. **Note:** This number **is not** a zero-based number. For example, for a build matrix with four jobs, the value of `job-total` is `4`. | +| `strategy.fail-fast` | `string` | When `true`, all in-progress jobs are canceled if any job in a matrix fails. For more information, see "[Workflow syntax for {% data variables.product.prodname_actions %}](/actions/learn-github-actions/workflow-syntax-for-github-actions#jobsjob_idstrategyfail-fast)." | +| `strategy.job-index` | `string` | The index of the current job in the matrix. **Note:** This number is a zero-based number. The first job's index in the matrix is `0`. | +| `strategy.job-total` | `string` | The total number of jobs in the matrix. **Note:** This number **is not** a zero-based number. For example, for a matrix with four jobs, the value of `job-total` is `4`. | | `strategy.max-parallel` | `string` | The maximum number of jobs that can run simultaneously when using a `matrix` job strategy. For more information, see "[Workflow syntax for {% data variables.product.prodname_actions %}](/actions/learn-github-actions/workflow-syntax-for-github-actions#jobsjob_idstrategymax-parallel)." | ### Example contents of the `strategy` context -The following example contents of the `strategy` context is from a build matrix with four jobs, and is taken from the final job. Note the difference between the zero-based `job-index` number, and `job-total` which is not zero-based. +The following example contents of the `strategy` context is from a matrix with four jobs, and is taken from the final job. Note the difference between the zero-based `job-index` number, and `job-total` which is not zero-based. ```yaml { @@ -577,7 +577,7 @@ The following example contents of the `strategy` context is from a build matrix ### Example usage of the `strategy` context -This example workflow uses the `strategy.job-index` property to set a unique name for a log file for each job in a build matrix. +This example workflow uses the `strategy.job-index` property to set a unique name for a log file for each job in a matrix. ```yaml{:copy} name: Test matrix @@ -602,18 +602,18 @@ jobs: ## `matrix` context -For workflows with a build matrix, the `matrix` context contains the matrix properties defined in the workflow file that apply to the current job. For example, if you configure a build matrix with the `os` and `node` keys, the `matrix` context object includes the `os` and `node` properties with the values that are being used for the current job. +For workflows with a matrix, the `matrix` context contains the matrix properties defined in the workflow file that apply to the current job. For example, if you configure a matrix with the `os` and `node` keys, the `matrix` context object includes the `os` and `node` properties with the values that are being used for the current job. There are no standard properties in the `matrix` context, only those which are defined in the workflow file. | Property name | Type | Description | |---------------|------|-------------| -| `matrix` | `object` | This context is only available for jobs in a build matrix, and changes for each job in a workflow run. You can access this context from any job or step in a workflow. This object contains the properties listed below. | +| `matrix` | `object` | This context is only available for jobs in a matrix, and changes for each job in a workflow run. You can access this context from any job or step in a workflow. This object contains the properties listed below. | | `matrix.` | `string` | The value of a matrix property. | ### Example contents of the `matrix` context -The following example contents of the `matrix` context is from a job in a build matrix that has the `os` and `node` matrix properties defined in the workflow. The job is executing the matrix combination of an `ubuntu-latest` OS and Node.js version `16`. +The following example contents of the `matrix` context is from a job in a matrix that has the `os` and `node` matrix properties defined in the workflow. The job is executing the matrix combination of an `ubuntu-latest` OS and Node.js version `16`. ```yaml { @@ -624,7 +624,7 @@ The following example contents of the `matrix` context is from a job in a build ### Example usage of the `matrix` context -This example workflow creates a build matrix with `os` and `node` keys. It uses the `matrix.os` property to set the runner type for each job, and uses the `matrix.node` property to set the Node.js version for each job. +This example workflow creates a matrix with `os` and `node` keys. It uses the `matrix.os` property to set the runner type for each job, and uses the `matrix.node` property to set the Node.js version for each job. ```yaml{:copy} name: Test matrix diff --git a/content/actions/migrating-to-github-actions/migrating-from-circleci-to-github-actions.md b/content/actions/migrating-to-github-actions/migrating-from-circleci-to-github-actions.md index 1c61cc8c558c..576e0f706ecd 100644 --- a/content/actions/migrating-to-github-actions/migrating-from-circleci-to-github-actions.md +++ b/content/actions/migrating-to-github-actions/migrating-from-circleci-to-github-actions.md @@ -50,7 +50,7 @@ Both CircleCI and {% data variables.product.prodname_actions %} configure `jobs` Both CircleCI and {% data variables.product.prodname_actions %} provide a mechanism to reuse and share tasks in a workflow. CircleCI uses a concept called orbs, written in YAML, to provide tasks that people can reuse in a workflow. {% data variables.product.prodname_actions %} has powerful and flexible reusable components called actions, which you build with either JavaScript files or Docker images. You can create actions by writing custom code that interacts with your repository in any way you'd like, including integrating with {% data variables.product.product_name %}'s APIs and any publicly available third-party API. For example, an action can publish npm modules, send SMS alerts when urgent issues are created, or deploy production-ready code. For more information, see "[Creating actions](/actions/creating-actions)." -CircleCI can reuse pieces of workflows with YAML anchors and aliases. {% data variables.product.prodname_actions %} supports the most common need for reusability using build matrixes. For more information about build matrixes, see "[Managing complex workflows](/actions/learn-github-actions/managing-complex-workflows/#using-a-build-matrix)." +CircleCI can reuse pieces of workflows with YAML anchors and aliases. {% data variables.product.prodname_actions %} supports the most common need for reusability using matrices. For more information about matrices, see "[Using a matrix for your jobs](/actions/using-jobs/using-a-matrix-for-your-jobs)." ## Using Docker images diff --git a/content/actions/migrating-to-github-actions/migrating-from-jenkins-to-github-actions.md b/content/actions/migrating-to-github-actions/migrating-from-jenkins-to-github-actions.md index ff04a6c387a6..ca409c3ec013 100644 --- a/content/actions/migrating-to-github-actions/migrating-from-jenkins-to-github-actions.md +++ b/content/actions/migrating-to-github-actions/migrating-from-jenkins-to-github-actions.md @@ -82,9 +82,9 @@ Jenkins can run the `stages` and `steps` in parallel, while {% data variables.pr | ------------- | ------------- | | [`parallel`](https://jenkins.io/doc/book/pipeline/syntax/#parallel) | [`jobs..strategy.max-parallel`](/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#jobsjob_idstrategymax-parallel) | -### Build matrix +### Matrix -Both {% data variables.product.prodname_actions %} and Jenkins let you use a build matrix to define various system combinations. +Both {% data variables.product.prodname_actions %} and Jenkins let you use a matrix to define various system combinations. | Jenkins | {% data variables.product.prodname_actions %} | | ------------- | ------------- | diff --git a/content/actions/migrating-to-github-actions/migrating-from-travis-ci-to-github-actions.md b/content/actions/migrating-to-github-actions/migrating-from-travis-ci-to-github-actions.md index fb1623dd409d..5d8af556f73a 100644 --- a/content/actions/migrating-to-github-actions/migrating-from-travis-ci-to-github-actions.md +++ b/content/actions/migrating-to-github-actions/migrating-from-travis-ci-to-github-actions.md @@ -60,9 +60,9 @@ Travis CI can use `stages` to run jobs in parallel. Similarly, {% data variables Travis CI and {% data variables.product.prodname_actions %} both support status badges, which let you indicate whether a build is passing or failing. For more information, see ["Adding a workflow status badge to your repository](/actions/managing-workflow-runs/adding-a-workflow-status-badge)." -### Using a build matrix +### Using a matrix -Travis CI and {% data variables.product.prodname_actions %} both support a build matrix, allowing you to perform testing using combinations of operating systems and software packages. For more information, see "[Using a build matrix](/actions/learn-github-actions/managing-complex-workflows#using-a-build-matrix)." +Travis CI and {% data variables.product.prodname_actions %} both support a matrix, allowing you to perform testing using combinations of operating systems and software packages. For more information, see "[Using a matrix for your jobs](/actions/using-jobs/using-a-matrix-for-your-jobs)." Below is an example comparing the syntax for each system: diff --git a/content/actions/using-jobs/index.md b/content/actions/using-jobs/index.md index 1a414c0c1df0..b579ac9323d3 100644 --- a/content/actions/using-jobs/index.md +++ b/content/actions/using-jobs/index.md @@ -13,7 +13,7 @@ children: - /using-jobs-in-a-workflow - /choosing-the-runner-for-a-job - /using-conditions-to-control-job-execution - - /using-a-build-matrix-for-your-jobs + - /using-a-matrix-for-your-jobs - /using-concurrency - /using-environments-for-jobs - /running-jobs-in-a-container diff --git a/content/actions/using-jobs/using-a-build-matrix-for-your-jobs.md b/content/actions/using-jobs/using-a-build-matrix-for-your-jobs.md deleted file mode 100644 index bb1844b8a74d..000000000000 --- a/content/actions/using-jobs/using-a-build-matrix-for-your-jobs.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Using a build matrix for your jobs -shortTitle: Using a build matrix for your jobs -intro: Create a build matrix and define variations for each job. -versions: - fpt: '*' - ghes: '*' - ghae: '*' - ghec: '*' -miniTocMaxHeadingLevel: 4 ---- - -{% data reusables.actions.enterprise-beta %} -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Overview - -{% data reusables.actions.jobs.section-using-a-build-matrix-for-your-jobs-strategy %} - -## Creating a matrix of different job configurations - -{% data reusables.actions.jobs.section-using-a-build-matrix-for-your-jobs-matrix %} - -## Canceling remaining jobs if a `matrix` job fails - -{% data reusables.actions.jobs.section-using-a-build-matrix-for-your-jobs-failfast %} - -## Defining the maximum number of concurrent jobs in a `matrix` - -{% data reusables.actions.jobs.section-using-a-build-matrix-for-your-jobs-max-parallel %} diff --git a/content/actions/using-jobs/using-a-matrix-for-your-jobs.md b/content/actions/using-jobs/using-a-matrix-for-your-jobs.md new file mode 100644 index 000000000000..40615bed484c --- /dev/null +++ b/content/actions/using-jobs/using-a-matrix-for-your-jobs.md @@ -0,0 +1,60 @@ +--- +title: Using a matrix for your jobs +shortTitle: Using a matrix +intro: Create a matrix to define variations for each job. +versions: + fpt: '*' + ghes: '*' + ghae: '*' + ghec: '*' +miniTocMaxHeadingLevel: 4 +redirect_from: + - /actions/using-jobs/using-a-build-matrix-for-your-jobs +--- + +{% data reusables.actions.enterprise-beta %} +{% data reusables.actions.enterprise-github-hosted-runners %} + +## About matrix strategies + +{% data reusables.actions.jobs.about-matrix-strategy %} + +## Using a matrix strategy + +{% data reusables.actions.jobs.using-matrix-strategy %} + +### Example: Using a single-dimension matrix + +{% data reusables.actions.jobs.single-dimension-matrix %} + +### Example: Using a multi-dimension matrix + +{% data reusables.actions.jobs.multi-dimension-matrix %} + +### Example: Using contexts to create matrices + +{% data reusables.actions.jobs.matrix-from-context %} + +## Expanding or adding matrix configurations + +{% data reusables.actions.jobs.matrix-include %} + +### Example: Expanding configurations + +{% data reusables.actions.jobs.matrix-expand-with-include %} + +### Example: Adding configurations + +{% data reusables.actions.jobs.matrix-add-with-include %} + +## Excluding matrix configurations + +{% data reusables.actions.jobs.matrix-exclude %} + +## Handling failures + +{% data reusables.actions.jobs.section-using-a-build-matrix-for-your-jobs-failfast %} + +## Defining the maximum number of concurrent jobs + +{% data reusables.actions.jobs.section-using-a-build-matrix-for-your-jobs-max-parallel %} diff --git a/content/actions/using-workflows/about-workflows.md b/content/actions/using-workflows/about-workflows.md index e052a37d037d..30762e5dd21a 100644 --- a/content/actions/using-workflows/about-workflows.md +++ b/content/actions/using-workflows/about-workflows.md @@ -105,9 +105,9 @@ jobs: For more information, see "[Defining prerequisite jobs](/actions/using-jobs/using-jobs-in-a-workflow#defining-prerequisite-jobs)." -### Using a build matrix +### Using a matrix -You can use a build matrix if you want your workflow to run tests across multiple combinations of parameters, such as operating systems, platforms, and languages. The build matrix is created using the `strategy` keyword, which receives the build options as an array. For example, this build matrix will run the job multiple times, using different versions of Node.js: +{% data reusables.actions.jobs.about-matrix-strategy %} The matrix is created using the `strategy` keyword, which receives the build options as an array. For example, this matrix will run the job multiple times, using different versions of Node.js: ```yaml jobs: @@ -115,14 +115,14 @@ jobs: runs-on: ubuntu-latest strategy: matrix: - node: [6, 8, 10] + node: [12, 14, 16] steps: - uses: {% data reusables.actions.action-setup-node %} with: node-version: {% raw %}${{ matrix.node }}{% endraw %} ``` -For more information, see "[Using a build matrix for your jobs](/actions/using-jobs/using-a-build-matrix-for-your-jobs)." +For more information, see "[Using a matrix for your jobs](/actions/using-jobs/using-a-matrix-for-your-jobs)." {% ifversion fpt or ghec %} ### Caching dependencies diff --git a/content/actions/using-workflows/workflow-syntax-for-github-actions.md b/content/actions/using-workflows/workflow-syntax-for-github-actions.md index 926f5966f034..c95bbcf20971 100644 --- a/content/actions/using-workflows/workflow-syntax-for-github-actions.md +++ b/content/actions/using-workflows/workflow-syntax-for-github-actions.md @@ -745,11 +745,39 @@ If the timeout exceeds the job execution time limit for the runner, the job will ## `jobs..strategy` -{% data reusables.actions.jobs.section-using-a-build-matrix-for-your-jobs-strategy %} +Use `jobs..strategy` to use a matrix strategy for your jobs. {% data reusables.actions.jobs.about-matrix-strategy %} For more information, see "[Using a matrix for your jobs](/actions/using-jobs/using-a-matrix-for-your-jobs)." ### `jobs..strategy.matrix` -{% data reusables.actions.jobs.section-using-a-build-matrix-for-your-jobs-matrix %} +{% data reusables.actions.jobs.using-matrix-strategy %} + +#### Example: Using a single-dimension matrix + +{% data reusables.actions.jobs.single-dimension-matrix %} + +#### Example: Using a multi-dimension matrix + +{% data reusables.actions.jobs.multi-dimension-matrix %} + +#### Example: Using contexts to create matrices + +{% data reusables.actions.jobs.matrix-from-context %} + +### `jobs..strategy.matrix.include` + +{% data reusables.actions.jobs.matrix-include %} + +#### Example: Expanding configurations + +{% data reusables.actions.jobs.matrix-expand-with-include %} + +#### Example: Adding configurations + +{% data reusables.actions.jobs.matrix-add-with-include %} + +### `jobs..strategy.matrix.exclude` + +{% data reusables.actions.jobs.matrix-exclude %} ### `jobs..strategy.fail-fast` diff --git a/content/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning.md b/content/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning.md index 6841ecf86f40..cccde8bdecc3 100644 --- a/content/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning.md +++ b/content/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning.md @@ -208,7 +208,7 @@ If this parameter is not used, the {% data variables.product.prodname_codeql_wor {% data reusables.code-scanning.codeql-languages-bullets %} -The default {% data variables.product.prodname_codeql_workflow %} file contains a build matrix called `language` which lists the languages in your repository that are analyzed. {% data variables.product.prodname_codeql %} automatically populates this matrix when you add {% data variables.product.prodname_code_scanning %} to a repository. Using the `language` matrix optimizes {% data variables.product.prodname_codeql %} to run each analysis in parallel. We recommend that all workflows adopt this configuration due to the performance benefits of parallelizing builds. For more information about build matrices, see "[Managing complex workflows](/actions/learn-github-actions/managing-complex-workflows#using-a-build-matrix)." +The default {% data variables.product.prodname_codeql_workflow %} file contains a matrix called `language` which lists the languages in your repository that are analyzed. {% data variables.product.prodname_codeql %} automatically populates this matrix when you add {% data variables.product.prodname_code_scanning %} to a repository. Using the `language` matrix optimizes {% data variables.product.prodname_codeql %} to run each analysis in parallel. We recommend that all workflows adopt this configuration due to the performance benefits of parallelizing builds. For more information about matrices, see "[Using a matrix for your jobs](/actions/using-jobs/using-a-matrix-for-your-jobs)." {% data reusables.code-scanning.specify-language-to-analyze %} diff --git a/content/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/troubleshooting-the-codeql-workflow.md b/content/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/troubleshooting-the-codeql-workflow.md index f3d53a8507cc..19757d051238 100644 --- a/content/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/troubleshooting-the-codeql-workflow.md +++ b/content/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/troubleshooting-the-codeql-workflow.md @@ -68,7 +68,7 @@ If an automatic build of code for a compiled language within your project fails, - Remove the `autobuild` step from your {% data variables.product.prodname_code_scanning %} workflow and add specific build steps. For information about editing the workflow, see "[Configuring {% data variables.product.prodname_code_scanning %}](/code-security/secure-coding/configuring-code-scanning#editing-a-code-scanning-workflow)." For more information about replacing the `autobuild` step, see "[Configuring the {% data variables.product.prodname_codeql %} workflow for compiled languages](/code-security/secure-coding/configuring-the-codeql-workflow-for-compiled-languages#adding-build-steps-for-a-compiled-language)." -- If your workflow doesn't explicitly specify the languages to analyze, {% data variables.product.prodname_codeql %} implicitly detects the supported languages in your code base. In this configuration, out of the compiled languages C/C++, C#, and Java, {% data variables.product.prodname_codeql %} only analyzes the language with the most source files. Edit the workflow and add a build matrix specifying the languages you want to analyze. The default CodeQL analysis workflow uses such a matrix. +- If your workflow doesn't explicitly specify the languages to analyze, {% data variables.product.prodname_codeql %} implicitly detects the supported languages in your code base. In this configuration, out of the compiled languages C/C++, C#, and Java, {% data variables.product.prodname_codeql %} only analyzes the language with the most source files. Edit the workflow and add a matrix specifying the languages you want to analyze. The default CodeQL analysis workflow uses such a matrix. The following extracts from a workflow show how you can use a matrix within the job strategy to specify languages, and then reference each language within the "Initialize {% data variables.product.prodname_codeql %}" step: @@ -190,7 +190,7 @@ If you use self-hosted runners to run {% data variables.product.prodname_codeql ### Use matrix builds to parallelize the analysis -The default {% data variables.product.prodname_codeql_workflow %} uses a build matrix of languages, which causes the analysis of each language to run in parallel. If you have specified the languages you want to analyze directly in the "Initialize CodeQL" step, analysis of each language will happen sequentially. To speed up analysis of multiple languages, modify your workflow to use a matrix. For more information, see the workflow extract in "[Automatic build for a compiled language fails](#automatic-build-for-a-compiled-language-fails)" above. +The default {% data variables.product.prodname_codeql_workflow %} uses a matrix of languages, which causes the analysis of each language to run in parallel. If you have specified the languages you want to analyze directly in the "Initialize CodeQL" step, analysis of each language will happen sequentially. To speed up analysis of multiple languages, modify your workflow to use a matrix. For more information, see the workflow extract in "[Automatic build for a compiled language fails](#automatic-build-for-a-compiled-language-fails)" above. ### Reduce the amount of code being analyzed in a single workflow diff --git a/contributing/content-templates.md b/contributing/content-templates.md index 89ac63763aa4..657a7f1cfdff 100644 --- a/contributing/content-templates.md +++ b/contributing/content-templates.md @@ -300,7 +300,7 @@ versions: - Include any additional features the setup action might provide that are useful to CI. - If applicable, provide examples of configuring exact versions or major/minor versions. - Include information about software already installed on GitHub-hosted runners or software configuration necessary to build and test the project. - - Provide examples of configuring build matrix strategies. + - Provide examples of configuring matrix strategies. - Link out to any docs about available software on the GitHub-hosted runners. (Ex. https://docs.github.com/en/actions/reference/software-installed-on-github-hosted-runners). - Include code samples. --> diff --git a/data/reusables/actions/jobs/about-matrix-strategy.md b/data/reusables/actions/jobs/about-matrix-strategy.md new file mode 100644 index 000000000000..6b7e9ceee1a5 --- /dev/null +++ b/data/reusables/actions/jobs/about-matrix-strategy.md @@ -0,0 +1 @@ +A matrix strategy lets you use variables in a single job definition to automatically create multiple job runs that are based the combinations of the variables. For example, you can use a matrix strategy to test your code in multiple versions of a language or on multiple operating systems. diff --git a/data/reusables/actions/jobs/matrix-add-with-include.md b/data/reusables/actions/jobs/matrix-add-with-include.md new file mode 100644 index 000000000000..166eb08dcbb1 --- /dev/null +++ b/data/reusables/actions/jobs/matrix-add-with-include.md @@ -0,0 +1,29 @@ +For example, this matrix will run 10 jobs, one for each combination of `os` and `version` in the matrix, plus a job for the `os` value of `windows-latest` and `version` value of `17`. + +```yaml +jobs: + example_matrix: + strategy: + matrix: + os: [macos-latest, windows-latest, ubuntu-latest] + version: [12, 14, 16] + include: + - os: windows-latest + version: 17 +``` + +If you don't specify any matrix variables, all configurations under `include` will run. For example, the following workflow would run two jobs, one for each `include` entry. This lets you take advantage of the matrix strategy without having a fully populated matrix. + +```yaml +jobs: + includes_only: + runs-on: ubuntu-latest + strategy: + matrix: + include: + - site: "production" + datacenter: "site-a" + - site: "staging" + datacenter: "site-b" + +``` \ No newline at end of file diff --git a/data/reusables/actions/jobs/matrix-exclude.md b/data/reusables/actions/jobs/matrix-exclude.md new file mode 100644 index 000000000000..6a3044674c03 --- /dev/null +++ b/data/reusables/actions/jobs/matrix-exclude.md @@ -0,0 +1,22 @@ +To remove specific configurations defined in the matrix, use `jobs..strategy.matrix.exclude`. An excluded configuration only has to be a partial match for it to be excluded. For example, the following workflow will run nine jobs: one job for each of the 12 configurations, minus the one excluded job that matches `{os: macos-latest, version: 12, environment: production}`, and the two excluded jobs that match `{os: windows-latest, version: 16}`. + +```yaml +strategy: + matrix: + os: [macos-latest, windows-latest] + version: [12, 14, 16] + environment: [staging, production] + exclude: + - os: macos-latest + version: 12 + environment: production + - os: windows-latest + version: 16 +runs-on: {% raw %}${{ matrix.os }}{% endraw %} +``` + +{% note %} + +**Note:** All `include` combinations are processed after `exclude`. This allows you to use `include` to add back combinations that were previously excluded. + +{% endnote %} diff --git a/data/reusables/actions/jobs/matrix-expand-with-include.md b/data/reusables/actions/jobs/matrix-expand-with-include.md new file mode 100644 index 000000000000..f8075468a54b --- /dev/null +++ b/data/reusables/actions/jobs/matrix-expand-with-include.md @@ -0,0 +1,22 @@ +For example, the following workflow will run six jobs, one for each combination of `os` and `node`. When the job for the `os` value of `windows-latest` and `node` value of `16` runs, an additional variable called `npm` with the value of `6` will be included in the job. + +```yaml +jobs: + example_matrix: + strategy: + matrix: + os: [windows-latest, ubuntu-latest] + node: [12, 14, 16] + include: + - os: windows-latest + node: 16 + npm: 6 + runs-on: {% raw %}${{ matrix.os }}{% endraw %} + steps: + - uses: {% data reusables.actions.action-setup-node %} + with: + node-version: {% raw %}${{ matrix.node }}{% endraw %} + - if: {% raw %}${{ matrix.npm }}{% endraw %} + run: npm install -g npm@{% raw %}${{ matrix.npm }}{% endraw %} + - run: npm --version +``` diff --git a/data/reusables/actions/jobs/matrix-from-context.md b/data/reusables/actions/jobs/matrix-from-context.md new file mode 100644 index 000000000000..f6eae717e84c --- /dev/null +++ b/data/reusables/actions/jobs/matrix-from-context.md @@ -0,0 +1,30 @@ +You can use contexts to create matrices. For more information about contexts, see "[Contexts](/actions/learn-github-actions/contexts)." + +For example, the following workflow triggers on the `repository_dispatch` event and uses information from the event payload to build the matrix. When a repository dispatch event is created with a payload like the one below, the matrix `version` variable will have a value of `[12, 14, 16]`. For more information about the `repository_dispatch` trigger, see "[Events that trigger workflows](/actions/using-workflows/events-that-trigger-workflows#repository_dispatch)." + +```json +{ + "event_type": "test", + "client_payload": { + "versions": [12, 14, 16] + } +} +``` + +```yaml +on: + repository_dispatch: + types: + - test + +jobs: + example_matrix: + runs-on: ubuntu-latest + strategy: + matrix: + version: {% raw %}${{ github.event.client_payload.versions }}{% endraw %} + steps: + - uses: {% data reusables.actions.action-setup-node %} + with: + node-version: {% raw %}${{ matrix.version }}{% endraw %} +``` diff --git a/data/reusables/actions/jobs/matrix-include.md b/data/reusables/actions/jobs/matrix-include.md new file mode 100644 index 000000000000..cf5e4b1a5d4a --- /dev/null +++ b/data/reusables/actions/jobs/matrix-include.md @@ -0,0 +1,38 @@ +Use `jobs..strategy.matrix.include` to expand existing matrix configurations or to add new configurations. The value of `include` is a list of objects. + +For each object in the `include` list, the key:value pairs in the object will be added to each of the matrix combinations if none of the key:value pairs overwrite any of the original matrix values. If the object cannot be added to any of the matrix combinations, a new matrix combination will be created instead. Note that the original matrix values will not be overwritten, but added matrix values can be overwritten. + +For example, this matrix: + +```yaml +strategy: + matrix: + fruit: [apple, pear] + animal: [cat, dog] + include: + - color: green + - color: pink + animal: cat + - fruit: apple + shape: circle + - fruit: banana + - fruit: banana + animal: cat +``` + +will result in six jobs with the following matrix combinations: + +- `{fruit: apple, animal: cat, color: pink, shape: circle}` +- `{fruit: apple, animal: dog, color: green, shape: circle}` +- `{fruit: pear, animal: cat, color: pink}` +- `{fruit: pear, animal: dog, color: green}` +- `{fruit: banana}` +- `{fruit: banana, animal: cat}` + +following this logic: + +- `{color: green}` is added to all of the original matrix combinations because it can be added without overwriting any part of the original combinations. +- `{color: pink, animal: cat}` adds `color:pink` only to the original matrix combinations that include `animal: cat`. This overwrites the `color: green` that was added by the previous `include` entry. +- `{fruit: apple, shape: circle}` adds `shape: circle` only to the original matrix combinations that include `fruit: apple`. +- `{fruit: banana}` cannot be added to any original matrix combination without overwriting a value, so it is added as an additional matrix combination. +- `{fruit: banana, animal: cat}` cannot be added to any original matrix combination without overwriting a value, so it is added as an additional matrix combination. It does not add to the `{fruit: banana}` matrix combination because that combination was not one of the original matrix combinations. diff --git a/data/reusables/actions/jobs/multi-dimension-matrix.md b/data/reusables/actions/jobs/multi-dimension-matrix.md new file mode 100644 index 000000000000..5041ca555407 --- /dev/null +++ b/data/reusables/actions/jobs/multi-dimension-matrix.md @@ -0,0 +1,22 @@ +You can specify multiple variables to create a multi-dimensional matrix. A job will run for each possible combination of the variables. + +For example, the following workflow specifies two variables: + +- Two operating systems specified in the `os` variable +- Three Node.js versions specified in the `version` variable + +The workflow will run six jobs, one for each combination of the `os` and `version` variables. Each job will set the `runs-on` value to the current `os` value and will pass the current `version` value to the `actions/setup-node` action. + +```yaml +jobs: + example_matrix: + strategy: + matrix: + os: [ubuntu-18.04, ubuntu-20.04] + version: [10, 12, 14] + runs-on: {% raw %}${{ matrix.os }}{% endraw %} + steps: + - uses: {% data reusables.actions.action-setup-node %} + with: + node-version: {% raw %}${{ matrix.version }}{% endraw %} +``` diff --git a/data/reusables/actions/jobs/section-using-a-build-matrix-for-your-jobs-failfast.md b/data/reusables/actions/jobs/section-using-a-build-matrix-for-your-jobs-failfast.md index 8d0675e225ea..e1bba5d92aa4 100644 --- a/data/reusables/actions/jobs/section-using-a-build-matrix-for-your-jobs-failfast.md +++ b/data/reusables/actions/jobs/section-using-a-build-matrix-for-your-jobs-failfast.md @@ -1 +1,23 @@ -When `jobs..strategy.fail-fast` is set to `true`, {% data variables.product.prodname_dotcom %} cancels all in-progress jobs in the matrix if any `matrix` job fails. Default: `true` +You can control how job failures are handled with `jobs..strategy.fail-fast` and `jobs..continue-on-error`. + +`jobs..strategy.fail-fast` applies to the entire matrix. If `jobs..strategy.fail-fast` is set to `true`, {% data variables.product.product_name %} will cancel all in-progress and queued jobs in the matrix if any job in the matrix fails. This property defaults to `true`. + +`jobs..continue-on-error` applies to a single job. If `jobs..continue-on-error` is `true`, other jobs in the matrix will continue running even if the job with `jobs..continue-on-error: true` fails. + +You can use `jobs..strategy.fail-fast` and `jobs..continue-on-error` together. For example, the following workflow will start four jobs. For each job, `continue-on-error` is determined by the value of `matrix.experimental`. If any of the jobs with `continue-on-error: false` fail, all jobs that are in progress or queued will be cancelled. If the job with `continue-on-error: true` fails, the other jobs will not be affected. + + +```yaml +jobs: + test: + runs-on: ubuntu-latest + continue-on-error: {% raw %}${{ matrix.experimental }}{% endraw %} + strategy: + fail-fast: true + matrix: + version: [6, 7, 8] + experimental: [false] + include: + - version: 9 + experimental: true +``` diff --git a/data/reusables/actions/jobs/section-using-a-build-matrix-for-your-jobs-matrix.md b/data/reusables/actions/jobs/section-using-a-build-matrix-for-your-jobs-matrix.md deleted file mode 100644 index c7d820b18151..000000000000 --- a/data/reusables/actions/jobs/section-using-a-build-matrix-for-your-jobs-matrix.md +++ /dev/null @@ -1,122 +0,0 @@ - -Use `jobs..strategy.matrix` to define a matrix of different job configurations. A matrix allows you to create multiple jobs by performing variable substitution in a single job definition. For example, you can use a matrix to create jobs for more than one supported version of a programming language, operating system, or tool. A matrix reuses the job's configuration and creates a job for each matrix you configure. - -{% data reusables.actions.usage-matrix-limits %} - -Each option you define in the `matrix` has a key and value. The keys you define become properties in the `matrix` context and you can reference the property in other areas of your workflow file. For example, if you define the key `os` that contains an array of operating systems, you can use the `matrix.os` property as the value of the `runs-on` keyword to create a job for each operating system. For more information, see "[Contexts](/actions/learn-github-actions/contexts)." - -The order that you define a `matrix` matters. The first option you define will be the first job that runs in your workflow. - -#### Example: Running multiple versions of Node.js - -You can specify a matrix by supplying an array for the configuration options. For example, if the runner supports Node.js versions 10, 12, and 14, you could specify an array of those versions in the `matrix`. - -This example creates a matrix of three jobs by setting the `node` key to an array of three Node.js versions. To use the matrix, the example sets the `matrix.node` context property as the value of the `setup-node` action's input parameter `node-version`. As a result, three jobs will run, each using a different Node.js version. - -```yaml -strategy: - matrix: - node: [10, 12, 14] -steps: - # Configures the node version used on GitHub-hosted runners - - uses: {% data reusables.actions.action-setup-node %} - with: - # The Node.js version to configure - node-version: {% raw %}${{ matrix.node }}{% endraw %} -``` - -The `setup-node` action is the recommended way to configure a Node.js version when using {% data variables.product.prodname_dotcom %}-hosted runners. For more information, see the [`setup-node`](https://github.com/actions/setup-node) action. - -#### Example: Running with multiple operating systems - -You can create a matrix to run workflows on more than one runner operating system. You can also specify more than one matrix configuration. This example creates a matrix of 6 jobs: - -- 2 operating systems specified in the `os` array -- 3 Node.js versions specified in the `node` array - -{% data reusables.repositories.actions-matrix-builds-os %} - -```yaml -runs-on: {% raw %}${{ matrix.os }}{% endraw %} -strategy: - matrix: - os: [ubuntu-18.04, ubuntu-20.04] - node: [10, 12, 14] -steps: - - uses: {% data reusables.actions.action-setup-node %} - with: - node-version: {% raw %}${{ matrix.node }}{% endraw %} -``` - -{% ifversion ghae %} -For more information about the configuration of self-hosted runners, see "[About self-hosted runners](/actions/hosting-your-own-runners/about-self-hosted-runners)." -{% else %}To find supported configuration options for {% data variables.product.prodname_dotcom %}-hosted runners, see "[Virtual environments for {% data variables.product.prodname_dotcom %}-hosted runners](/actions/automating-your-workflow-with-github-actions/virtual-environments-for-github-hosted-runners)." -{% endif %} - -#### Example: Including additional values in combinations - -You can add additional configuration options to a build matrix job that already exists. For example, if you want to use a specific version of `npm` when the job that uses `windows-latest` and version 8 of `node` runs, you can use `include` to specify that additional option. - -{% raw %} -```yaml -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 -``` -{% endraw %} - -#### Example: Including new combinations - -You can use `include` to add new jobs to a build matrix. Any unmatched include configurations are added to the matrix. For example, if you want to use `node` version 14 to build on multiple operating systems, but wanted one extra experimental job using node version 15 on Ubuntu, you can use `include` to specify that additional job. - -{% raw %} -```yaml -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 -``` -{% endraw %} - -#### Example: Excluding configurations from a matrix - -You can remove a specific configurations defined in the build matrix using the `exclude` option. Using `exclude` removes a job defined by the build matrix. The number of jobs is the cross product of the number of operating systems (`os`) included in the arrays you provide, minus any subtractions (`exclude`). - -{% raw %} -```yaml -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 -``` -{% endraw %} - -{% note %} - -**Note:** All `include` combinations are processed after `exclude`. This allows you to use `include` to add back combinations that were previously excluded. - -{% endnote %} - -### Using environment variables in a matrix - -You can add custom environment variables for each test combination by using the `include` key. You can then refer to the custom environment variables in a later step. - -{% data reusables.actions.matrix-variable-example %} diff --git a/data/reusables/actions/jobs/section-using-a-build-matrix-for-your-jobs-max-parallel.md b/data/reusables/actions/jobs/section-using-a-build-matrix-for-your-jobs-max-parallel.md index 224396244abc..fd58b0c321b1 100644 --- a/data/reusables/actions/jobs/section-using-a-build-matrix-for-your-jobs-max-parallel.md +++ b/data/reusables/actions/jobs/section-using-a-build-matrix-for-your-jobs-max-parallel.md @@ -1,6 +1,13 @@ -Use `jobs..strategy.max-parallel` to set the maximum number of jobs that can run simultaneously when using a `matrix` job strategy. By default, {% data variables.product.prodname_dotcom %} will maximize the number of jobs run in parallel depending on the available runners on {% data variables.product.prodname_dotcom %}-hosted virtual machines. +By default, {% data variables.product.product_name %} will maximize the number of jobs run in parallel depending on runner availability. To set the maximum number of jobs that can run simultaneously when using a `matrix` job strategy, use `jobs..strategy.max-parallel`. + +For example, the following workflow will run a maximum of two jobs at a time, even if there are runners available to run all six jobs at once. ```yaml -strategy: - max-parallel: 2 +jobs: + example_matrix: + strategy: + max-parallel: 2 + matrix: + version: [10, 12, 14] + os: [ubuntu-latest, windows-latest] ``` diff --git a/data/reusables/actions/jobs/section-using-a-build-matrix-for-your-jobs-strategy.md b/data/reusables/actions/jobs/section-using-a-build-matrix-for-your-jobs-strategy.md deleted file mode 100644 index c4f74652af86..000000000000 --- a/data/reusables/actions/jobs/section-using-a-build-matrix-for-your-jobs-strategy.md +++ /dev/null @@ -1 +0,0 @@ -Use `jobs..strategy` to create a build matrix for your jobs. You can define different variations to run each job in. diff --git a/data/reusables/actions/jobs/single-dimension-matrix.md b/data/reusables/actions/jobs/single-dimension-matrix.md new file mode 100644 index 000000000000..252ff4456837 --- /dev/null +++ b/data/reusables/actions/jobs/single-dimension-matrix.md @@ -0,0 +1,15 @@ +You can specify a single variable to create a single-dimension matrix. + +For example, the following workflow defines the variable `version` with the values `[10, 12, 14]`. The workflow will run three jobs, one for each value in the variable. Each job will access the `version` value through the `matrix.version` context and pass the value as `node-version` to the `actions/setup-node` action. + +```yaml +jobs: + example_matrix: + strategy: + matrix: + version: [10, 12, 14] + steps: + - uses: {% data reusables.actions.action-setup-node %} + with: + node-version: {% raw %}${{ matrix.version }}{% endraw %} +``` diff --git a/data/reusables/actions/jobs/using-matrix-strategy.md b/data/reusables/actions/jobs/using-matrix-strategy.md new file mode 100644 index 000000000000..58d520c087b6 --- /dev/null +++ b/data/reusables/actions/jobs/using-matrix-strategy.md @@ -0,0 +1,25 @@ +Use `jobs..strategy.matrix` to define a matrix of different job configurations. Within your matrix, define one or more variables followed by an array of values. For example, the following matrix has a veriable called `version` with the value `[10, 12, 14]` and a variable called `os` with the value `[ubuntu-latest, windows-latest]`: + +```yaml +jobs: + example_matrix: + strategy: + matrix: + version: [10, 12, 14] + os: [ubuntu-latest, windows-latest] +``` + +A job will run for each possible combination of the variables. In this example, the workflow will run six jobs, one for each combination of the `os` and `version` variables. + +By default, {% data variables.product.product_name %} will maximize the number of jobs run in parallel depending on runner availability. The order of the variables in the matrix determines the order in which the jobs are created. The first variable you define will be the first job that is created in your workflow run. For example, the above matrix will create the jobs in the following order: + +- `{version: 10, os: ubuntu-latest}` +- `{version: 10, os: windows-latest}` +- `{version: 12, os: ubuntu-latest}` +- `{version: 12, os: windows-latest}` +- `{version: 14, os: ubuntu-latest}` +- `{version: 14, os: windows-latest}` + +A matrix will generate a maximum of 256 jobs per workflow run. This limit applies to both {% data variables.product.product_name %}-hosted and self-hosted runners. + +The variables that you define become properties in the `matrix` context, and you can reference the property in other areas of your workflow file. In this example, you can use `matrix.version` and `matrix.os` to access the current value of `version` and `os` that the job is using. For more information, see "[Contexts](/actions/learn-github-actions/contexts)." diff --git a/data/reusables/repositories/actions-matrix-builds-os.md b/data/reusables/repositories/actions-matrix-builds-os.md deleted file mode 100644 index 228b240dafb1..000000000000 --- a/data/reusables/repositories/actions-matrix-builds-os.md +++ /dev/null @@ -1 +0,0 @@ -When you define a matrix of operating systems, you must set the value of `runs-on` to the `matrix.os` context property you defined.