From 4e34c693418f4444c152a6726e0c6f1834557bbd Mon Sep 17 00:00:00 2001 From: hubwriter Date: Thu, 18 Jul 2024 08:53:14 +0100 Subject: [PATCH 1/3] Actions: fix heading level sequence for 2 articles (#51680) Co-authored-by: Joe Clark <31087804+jc-clark@users.noreply.github.com> --- .../using-workflows/triggering-a-workflow.md | 48 ++++++++++- .../workflow-syntax-for-github-actions.md | 46 +++++++++- .../run-on-specific-branches-or-tags1.md | 10 +++ .../run-on-specific-branches-or-tags2.md | 21 +++++ .../run-on-specific-branches-or-tags3.md | 20 +++++ .../run-on-specific-branches-or-tags4.md | 18 ++++ ...ection-run-on-specific-branches-or-tags.md | 77 ----------------- .../section-triggering-a-workflow-branches.md | 66 -------------- .../section-triggering-a-workflow-paths.md | 85 ------------------- .../workflows/triggering-a-workflow-paths1.md | 13 +++ .../workflows/triggering-a-workflow-paths2.md | 12 +++ .../workflows/triggering-a-workflow-paths3.md | 10 +++ .../workflows/triggering-a-workflow-paths4.md | 18 ++++ .../workflows/triggering-a-workflow-paths5.md | 13 +++ .../triggering-workflow-branches1.md | 7 ++ .../triggering-workflow-branches2.md | 19 +++++ .../triggering-workflow-branches3.md | 13 +++ .../triggering-workflow-branches4.md | 18 ++++ 18 files changed, 279 insertions(+), 235 deletions(-) create mode 100644 data/reusables/actions/workflows/run-on-specific-branches-or-tags1.md create mode 100644 data/reusables/actions/workflows/run-on-specific-branches-or-tags2.md create mode 100644 data/reusables/actions/workflows/run-on-specific-branches-or-tags3.md create mode 100644 data/reusables/actions/workflows/run-on-specific-branches-or-tags4.md delete mode 100644 data/reusables/actions/workflows/section-run-on-specific-branches-or-tags.md delete mode 100644 data/reusables/actions/workflows/section-triggering-a-workflow-branches.md delete mode 100644 data/reusables/actions/workflows/section-triggering-a-workflow-paths.md create mode 100644 data/reusables/actions/workflows/triggering-a-workflow-paths1.md create mode 100644 data/reusables/actions/workflows/triggering-a-workflow-paths2.md create mode 100644 data/reusables/actions/workflows/triggering-a-workflow-paths3.md create mode 100644 data/reusables/actions/workflows/triggering-a-workflow-paths4.md create mode 100644 data/reusables/actions/workflows/triggering-a-workflow-paths5.md create mode 100644 data/reusables/actions/workflows/triggering-workflow-branches1.md create mode 100644 data/reusables/actions/workflows/triggering-workflow-branches2.md create mode 100644 data/reusables/actions/workflows/triggering-workflow-branches3.md create mode 100644 data/reusables/actions/workflows/triggering-workflow-branches4.md diff --git a/content/actions/using-workflows/triggering-a-workflow.md b/content/actions/using-workflows/triggering-a-workflow.md index f9c8fe5f945f..be2eddb6af51 100644 --- a/content/actions/using-workflows/triggering-a-workflow.md +++ b/content/actions/using-workflows/triggering-a-workflow.md @@ -12,7 +12,7 @@ topics: - CI - CD --- - + {% data reusables.actions.enterprise-github-hosted-runners %} ## About workflow triggers @@ -103,15 +103,55 @@ You can use activity types and filters to further control when your workflow wil ### Using filters to target specific branches for pull request events -{% data reusables.actions.workflows.section-triggering-a-workflow-branches %} +{% data reusables.actions.workflows.triggering-workflow-branches1 %} + +#### Example: Including branches + +{% data reusables.actions.workflows.triggering-workflow-branches2 %} + +#### Example: Excluding branches + +{% data reusables.actions.workflows.triggering-workflow-branches3 %} + +#### Example: Including and excluding branches + +{% data reusables.actions.workflows.triggering-workflow-branches4 %} ### Using filters to target specific branches or tags for push events -{% data reusables.actions.workflows.section-run-on-specific-branches-or-tags %} +{% data reusables.actions.workflows.run-on-specific-branches-or-tags1 %} + +#### Example: Including branches and tags + +{% data reusables.actions.workflows.run-on-specific-branches-or-tags2 %} + +#### Example: Excluding branches and tags + +{% data reusables.actions.workflows.run-on-specific-branches-or-tags3 %} + +#### Example: Including and excluding branches and tags + +{% data reusables.actions.workflows.run-on-specific-branches-or-tags4 %} ### Using filters to target specific paths for pull request or push events -{% data reusables.actions.workflows.section-triggering-a-workflow-paths %} +{% data reusables.actions.workflows.triggering-a-workflow-paths1 %} + +#### Example: Including paths + +{% data reusables.actions.workflows.triggering-a-workflow-paths2 %} + +#### Example: Excluding paths + +{% data reusables.actions.workflows.triggering-a-workflow-paths3 %} + +#### Example: Including and excluding paths + +{% data reusables.actions.workflows.triggering-a-workflow-paths4 %} + +#### Git diff comparisons + +{% data reusables.actions.workflows.triggering-a-workflow-paths5 %} ### Using filters to target specific branches for workflow run events 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 001ef55026d6..0350093bb8ed 100644 --- a/content/actions/using-workflows/workflow-syntax-for-github-actions.md +++ b/content/actions/using-workflows/workflow-syntax-for-github-actions.md @@ -52,15 +52,55 @@ run-name: Deploy to ${{ inputs.deploy_target }} by @${{ github.actor }} ## `on..` -{% data reusables.actions.workflows.section-triggering-a-workflow-branches %} +{% data reusables.actions.workflows.triggering-workflow-branches1 %} + +### Example: Including branches + +{% data reusables.actions.workflows.triggering-workflow-branches2 %} + +### Example: Excluding branches + +{% data reusables.actions.workflows.triggering-workflow-branches3 %} + +### Example: Including and excluding branches + +{% data reusables.actions.workflows.triggering-workflow-branches4 %} ## `on.push.` -{% data reusables.actions.workflows.section-run-on-specific-branches-or-tags %} +{% data reusables.actions.workflows.run-on-specific-branches-or-tags1 %} + +### Example: Including branches and tags + +{% data reusables.actions.workflows.run-on-specific-branches-or-tags2 %} + +### Example: Excluding branches and tags + +{% data reusables.actions.workflows.run-on-specific-branches-or-tags3 %} + +### Example: Including and excluding branches and tags + +{% data reusables.actions.workflows.run-on-specific-branches-or-tags4 %} ## `on..` -{% data reusables.actions.workflows.section-triggering-a-workflow-paths %} +{% data reusables.actions.workflows.triggering-a-workflow-paths1 %} + +### Example: Including paths + +{% data reusables.actions.workflows.triggering-a-workflow-paths2 %} + +### Example: Excluding paths + +{% data reusables.actions.workflows.triggering-a-workflow-paths3 %} + +### Example: Including and excluding paths + +{% data reusables.actions.workflows.triggering-a-workflow-paths4 %} + +### Git diff comparisons + +{% data reusables.actions.workflows.triggering-a-workflow-paths5 %} ## `on.schedule` diff --git a/data/reusables/actions/workflows/run-on-specific-branches-or-tags1.md b/data/reusables/actions/workflows/run-on-specific-branches-or-tags1.md new file mode 100644 index 000000000000..5a1fcf65ab26 --- /dev/null +++ b/data/reusables/actions/workflows/run-on-specific-branches-or-tags1.md @@ -0,0 +1,10 @@ + +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`/`tags-ignore` or only `branches`/`branches-ignore`, the workflow won't run for events affecting the undefined Git ref. If you define neither `tags`/`tags-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`/`paths-ignore`](/actions/using-workflows/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpathspaths-ignore), the workflow will only run when both filters are satisfied. + +The `branches`, `branches-ignore`, `tags`, and `tags-ignore` keywords accept glob patterns that use characters like `*`, `**`, `+`, `?`, `!` and others to match more than one branch or tag 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 `\`. For more information about glob patterns, see the "[AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#filter-pattern-cheat-sheet)." diff --git a/data/reusables/actions/workflows/run-on-specific-branches-or-tags2.md b/data/reusables/actions/workflows/run-on-specific-branches-or-tags2.md new file mode 100644 index 000000000000..48e4960f5f45 --- /dev/null +++ b/data/reusables/actions/workflows/run-on-specific-branches-or-tags2.md @@ -0,0 +1,21 @@ +The patterns defined in `branches` and `tags` are evaluated against the Git ref's name. 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`) + +```yaml +on: + push: + # Sequence of patterns matched against refs/heads + branches: + - main + - 'mona/octocat' + - 'releases/**' + # Sequence of patterns matched against refs/tags + tags: + - v2 + - v1.* +``` diff --git a/data/reusables/actions/workflows/run-on-specific-branches-or-tags3.md b/data/reusables/actions/workflows/run-on-specific-branches-or-tags3.md new file mode 100644 index 000000000000..f17c333a32d4 --- /dev/null +++ b/data/reusables/actions/workflows/run-on-specific-branches-or-tags3.md @@ -0,0 +1,20 @@ + +When a pattern matches the `branches-ignore` or `tags-ignore` pattern, the workflow will not run. The patterns defined in `branches` and `tags` are evaluated against the Git ref's name. 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 `releases/beta/3-alpha` (`refs/heads/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`) + +```yaml +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.* +``` diff --git a/data/reusables/actions/workflows/run-on-specific-branches-or-tags4.md b/data/reusables/actions/workflows/run-on-specific-branches-or-tags4.md new file mode 100644 index 000000000000..994269522990 --- /dev/null +++ b/data/reusables/actions/workflows/run-on-specific-branches-or-tags4.md @@ -0,0 +1,18 @@ +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. + +The order that you define patterns matters. + +* A matching negative pattern (prefixed with `!`) after a positive match will exclude the Git ref. +* A matching positive pattern after a negative match will include the Git ref again. + +The following workflow will run on pushes to `releases/10` or `releases/beta/mona`, but not on `releases/10-alpha` or `releases/beta/3-alpha` because the negative pattern `!releases/**-alpha` follows the positive pattern. + +```yaml +on: + push: + branches: + - 'releases/**' + - '!releases/**-alpha' +``` diff --git a/data/reusables/actions/workflows/section-run-on-specific-branches-or-tags.md b/data/reusables/actions/workflows/section-run-on-specific-branches-or-tags.md deleted file mode 100644 index 328c5d692945..000000000000 --- a/data/reusables/actions/workflows/section-run-on-specific-branches-or-tags.md +++ /dev/null @@ -1,77 +0,0 @@ - -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`/`tags-ignore` or only `branches`/`branches-ignore`, the workflow won't run for events affecting the undefined Git ref. If you define neither `tags`/`tags-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`/`paths-ignore`](/actions/using-workflows/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpathspaths-ignore), the workflow will only run when both filters are satisfied. - -The `branches`, `branches-ignore`, `tags`, and `tags-ignore` keywords accept glob patterns that use characters like `*`, `**`, `+`, `?`, `!` and others to match more than one branch or tag 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 `\`. For more information about glob patterns, see the "[AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#filter-pattern-cheat-sheet)." - -#### Example: Including branches and tags - -The patterns defined in `branches` and `tags` are evaluated against the Git ref's name. 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`) - -```yaml -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. The patterns defined in `branches` and `tags` are evaluated against the Git ref's name. 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 `releases/beta/3-alpha` (`refs/heads/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`) - -```yaml -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. - -The order that you define patterns matters. - -* A matching negative pattern (prefixed with `!`) after a positive match will exclude the Git ref. -* A matching positive pattern after a negative match will include the Git ref again. - -The following workflow will run on pushes to `releases/10` or `releases/beta/mona`, but not on `releases/10-alpha` or `releases/beta/3-alpha` because the negative pattern `!releases/**-alpha` follows the positive pattern. - -```yaml -on: - push: - branches: - - 'releases/**' - - '!releases/**-alpha' -``` diff --git a/data/reusables/actions/workflows/section-triggering-a-workflow-branches.md b/data/reusables/actions/workflows/section-triggering-a-workflow-branches.md deleted file mode 100644 index 4acdcc3abcef..000000000000 --- a/data/reusables/actions/workflows/section-triggering-a-workflow-branches.md +++ /dev/null @@ -1,66 +0,0 @@ -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`/`paths-ignore`](/actions/using-workflows/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpathspaths-ignore), 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 `\`. For more information about glob patterns, see the "[AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#filter-pattern-cheat-sheet)." - -#### 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`) - -```yaml -on: - pull_request: - # Sequence of patterns matched against refs/heads - branches: - - main - - 'mona/octocat' - - 'releases/**' -``` - -{% data reusables.pull_requests.path-filtering-required-workflows %} - -If a workflow is skipped due to branch filtering, [path filtering](/actions/using-workflows/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpathspaths-ignore), or a [commit message](/actions/managing-workflow-runs/skipping-workflow-runs), then checks associated with that workflow will remain in a "Pending" state. A pull request that requires those checks to be successful will be blocked from merging. - -#### Example: Excluding branches - -When a pattern matches the `branches-ignore` pattern, the workflow will not run. The patterns defined in `branches-ignore` 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 `releases/beta/3-alpha` (`refs/heads/releases/beta/3-alpha`) - -```yaml -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. - -The order that you define patterns matters. - -* A matching negative pattern (prefixed with `!`) after a positive match will exclude the Git ref. -* A matching positive pattern after a negative match will include the Git ref again. - -The following workflow will run on `pull_request` events for pull requests that target `releases/10` or `releases/beta/mona`, but not for pull requests that target `releases/10-alpha` or `releases/beta/3-alpha` because the negative pattern `!releases/**-alpha` follows the positive pattern. - -```yaml -on: - pull_request: - branches: - - 'releases/**' - - '!releases/**-alpha' -``` diff --git a/data/reusables/actions/workflows/section-triggering-a-workflow-paths.md b/data/reusables/actions/workflows/section-triggering-a-workflow-paths.md deleted file mode 100644 index bf8e1d7f1352..000000000000 --- a/data/reusables/actions/workflows/section-triggering-a-workflow-paths.md +++ /dev/null @@ -1,85 +0,0 @@ - -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 want to both include and exclude path patterns for a single event, use the `paths` filter prefixed with the `!` character to indicate which paths should be excluded. - -{% note %} - -**Note:** The order that you define `paths` patterns matters: - -* A matching negative pattern (prefixed with `!`) after a positive match will exclude the path. -* A matching positive pattern after a negative match will include the path again. - -{% endnote %} - -If you define both `branches`/`branches-ignore` and `paths`/`paths-ignore`, 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. For more information, see the "[AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#filter-pattern-cheat-sheet)." - -#### Example: Including paths - -If at least one path matches a pattern in the `paths` filter, the workflow runs. For example, the following workflow would run anytime you push a JavaScript file (`.js`). - -```yaml -on: - push: - paths: - - '**.js' -``` - -{% data reusables.pull_requests.path-filtering-required-workflows %} - -If a workflow is skipped due to path filtering, [branch filtering](/actions/using-workflows/workflow-syntax-for-github-actions#onpull_requestpull_request_targetbranchesbranches-ignore), or a [commit message](/actions/managing-workflow-runs/skipping-workflow-runs), then checks associated with that workflow will remain in a "Pending" state. A pull request that requires those checks to be successful will be blocked from merging. - -#### Example: Excluding paths - -When all the path names match patterns in `paths-ignore`, the workflow will not run. If any path names do not match patterns in `paths-ignore`, even if some path names match the patterns, the workflow will run. - -A workflow with the following path filter will only run on `push` events that include at least one file outside the `docs` directory at the root of the repository. - -```yaml -on: - push: - paths-ignore: - - 'docs/**' -``` - -#### Example: Including and excluding paths - -You cannot 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 prefixed 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. - -The order that you define `paths` patterns matters: - -* A matching negative pattern (prefixed with `!`) after a positive match will exclude the path. -* A matching positive pattern after a negative match will include the path again. - -This example runs anytime the `push` event includes a file in the `sub-project` directory or its subdirectories, unless the file is in the `sub-project/docs` directory. For example, a push that changed `sub-project/index.js` or `sub-project/src/index.js` will trigger a workflow run, but a push changing only `sub-project/docs/readme.md` will not. - -```yaml -on: - push: - paths: - - 'sub-project/**' - - '!sub-project/docs/**' -``` - -#### Git diff comparisons - -{% note %} - -**Note:** If you push more than 1,000 commits, or if {% data variables.product.prodname_dotcom %} does not generate the diff due to a timeout, the workflow will always run. - -{% endnote %} - -The filter determines if a workflow should run by evaluating the changed files and running them against the `paths-ignore` or `paths` list. If there are no files changed, the workflow will not run. - -{% data variables.product.prodname_dotcom %} generates the list of changed files using two-dot diffs for pushes and three-dot diffs for pull requests: -* **Pull requests:** Three-dot diffs are a comparison between the most recent version of the topic branch and the commit where the topic branch was last synced with the base branch. -* **Pushes to existing branches:** A two-dot diff compares the head and base SHAs directly with each other. -* **Pushes to new branches:** A two-dot diff against the parent of the ancestor of the deepest commit pushed. - -Diffs are limited to 300 files. If there are files changed that aren't matched in the first 300 files returned by the filter, the workflow will not run. You may need to create more specific filters so that the workflow will run automatically. - -For more information, see "[AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-comparing-branches-in-pull-requests)." diff --git a/data/reusables/actions/workflows/triggering-a-workflow-paths1.md b/data/reusables/actions/workflows/triggering-a-workflow-paths1.md new file mode 100644 index 000000000000..454eedbdc59f --- /dev/null +++ b/data/reusables/actions/workflows/triggering-a-workflow-paths1.md @@ -0,0 +1,13 @@ +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 want to both include and exclude path patterns for a single event, use the `paths` filter prefixed with the `!` character to indicate which paths should be excluded. + +> [!NOTE] +> The order that you define `paths` patterns matters: +> +> * A matching negative pattern (prefixed with `!`) after a positive match will exclude the path. +> * A matching positive pattern after a negative match will include the path again. + +If you define both `branches`/`branches-ignore` and `paths`/`paths-ignore`, 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. For more information, see the "[AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#filter-pattern-cheat-sheet)." diff --git a/data/reusables/actions/workflows/triggering-a-workflow-paths2.md b/data/reusables/actions/workflows/triggering-a-workflow-paths2.md new file mode 100644 index 000000000000..77a69daf43c8 --- /dev/null +++ b/data/reusables/actions/workflows/triggering-a-workflow-paths2.md @@ -0,0 +1,12 @@ +If at least one path matches a pattern in the `paths` filter, the workflow runs. For example, the following workflow would run anytime you push a JavaScript file (`.js`). + +```yaml +on: + push: + paths: + - '**.js' +``` + +{% data reusables.pull_requests.path-filtering-required-workflows %} + +If a workflow is skipped due to path filtering, [branch filtering](/actions/using-workflows/workflow-syntax-for-github-actions#onpull_requestpull_request_targetbranchesbranches-ignore), or a [commit message](/actions/managing-workflow-runs/skipping-workflow-runs), then checks associated with that workflow will remain in a "Pending" state. A pull request that requires those checks to be successful will be blocked from merging. diff --git a/data/reusables/actions/workflows/triggering-a-workflow-paths3.md b/data/reusables/actions/workflows/triggering-a-workflow-paths3.md new file mode 100644 index 000000000000..46a6e49d574d --- /dev/null +++ b/data/reusables/actions/workflows/triggering-a-workflow-paths3.md @@ -0,0 +1,10 @@ +When all the path names match patterns in `paths-ignore`, the workflow will not run. If any path names do not match patterns in `paths-ignore`, even if some path names match the patterns, the workflow will run. + +A workflow with the following path filter will only run on `push` events that include at least one file outside the `docs` directory at the root of the repository. + +```yaml +on: + push: + paths-ignore: + - 'docs/**' +``` diff --git a/data/reusables/actions/workflows/triggering-a-workflow-paths4.md b/data/reusables/actions/workflows/triggering-a-workflow-paths4.md new file mode 100644 index 000000000000..74b33a7a8632 --- /dev/null +++ b/data/reusables/actions/workflows/triggering-a-workflow-paths4.md @@ -0,0 +1,18 @@ +You cannot 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 prefixed 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. + +The order that you define `paths` patterns matters: + +* A matching negative pattern (prefixed with `!`) after a positive match will exclude the path. +* A matching positive pattern after a negative match will include the path again. + +This example runs anytime the `push` event includes a file in the `sub-project` directory or its subdirectories, unless the file is in the `sub-project/docs` directory. For example, a push that changed `sub-project/index.js` or `sub-project/src/index.js` will trigger a workflow run, but a push changing only `sub-project/docs/readme.md` will not. + +```yaml +on: + push: + paths: + - 'sub-project/**' + - '!sub-project/docs/**' +``` diff --git a/data/reusables/actions/workflows/triggering-a-workflow-paths5.md b/data/reusables/actions/workflows/triggering-a-workflow-paths5.md new file mode 100644 index 000000000000..5cf3803708d7 --- /dev/null +++ b/data/reusables/actions/workflows/triggering-a-workflow-paths5.md @@ -0,0 +1,13 @@ +> [!NOTE] +> If you push more than 1,000 commits, or if {% data variables.product.prodname_dotcom %} does not generate the diff due to a timeout, the workflow will always run. + +The filter determines if a workflow should run by evaluating the changed files and running them against the `paths-ignore` or `paths` list. If there are no files changed, the workflow will not run. + +{% data variables.product.prodname_dotcom %} generates the list of changed files using two-dot diffs for pushes and three-dot diffs for pull requests: +* **Pull requests:** Three-dot diffs are a comparison between the most recent version of the topic branch and the commit where the topic branch was last synced with the base branch. +* **Pushes to existing branches:** A two-dot diff compares the head and base SHAs directly with each other. +* **Pushes to new branches:** A two-dot diff against the parent of the ancestor of the deepest commit pushed. + +Diffs are limited to 300 files. If there are files changed that aren't matched in the first 300 files returned by the filter, the workflow will not run. You may need to create more specific filters so that the workflow will run automatically. + +For more information, see "[AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-comparing-branches-in-pull-requests)." diff --git a/data/reusables/actions/workflows/triggering-workflow-branches1.md b/data/reusables/actions/workflows/triggering-workflow-branches1.md new file mode 100644 index 000000000000..d544dcbb0a24 --- /dev/null +++ b/data/reusables/actions/workflows/triggering-workflow-branches1.md @@ -0,0 +1,7 @@ +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`/`paths-ignore`](/actions/using-workflows/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpathspaths-ignore), 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 `\`. For more information about glob patterns, see the "[AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#filter-pattern-cheat-sheet)." diff --git a/data/reusables/actions/workflows/triggering-workflow-branches2.md b/data/reusables/actions/workflows/triggering-workflow-branches2.md new file mode 100644 index 000000000000..0ad8c1a9bf3f --- /dev/null +++ b/data/reusables/actions/workflows/triggering-workflow-branches2.md @@ -0,0 +1,19 @@ +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`) + +```yaml +on: + pull_request: + # Sequence of patterns matched against refs/heads + branches: + - main + - 'mona/octocat' + - 'releases/**' +``` + +{% data reusables.pull_requests.path-filtering-required-workflows %} + +If a workflow is skipped due to branch filtering, [path filtering](/actions/using-workflows/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpathspaths-ignore), or a [commit message](/actions/managing-workflow-runs/skipping-workflow-runs), then checks associated with that workflow will remain in a "Pending" state. A pull request that requires those checks to be successful will be blocked from merging. diff --git a/data/reusables/actions/workflows/triggering-workflow-branches3.md b/data/reusables/actions/workflows/triggering-workflow-branches3.md new file mode 100644 index 000000000000..0e7d8670ca24 --- /dev/null +++ b/data/reusables/actions/workflows/triggering-workflow-branches3.md @@ -0,0 +1,13 @@ +When a pattern matches the `branches-ignore` pattern, the workflow will not run. The patterns defined in `branches-ignore` 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 `releases/beta/3-alpha` (`refs/heads/releases/beta/3-alpha`) + +```yaml +on: + pull_request: + # Sequence of patterns matched against refs/heads + branches-ignore: + - 'mona/octocat' + - 'releases/**-alpha' +``` diff --git a/data/reusables/actions/workflows/triggering-workflow-branches4.md b/data/reusables/actions/workflows/triggering-workflow-branches4.md new file mode 100644 index 000000000000..c75a7b01ed5c --- /dev/null +++ b/data/reusables/actions/workflows/triggering-workflow-branches4.md @@ -0,0 +1,18 @@ +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. + +The order that you define patterns matters. + +* A matching negative pattern (prefixed with `!`) after a positive match will exclude the Git ref. +* A matching positive pattern after a negative match will include the Git ref again. + +The following workflow will run on `pull_request` events for pull requests that target `releases/10` or `releases/beta/mona`, but not for pull requests that target `releases/10-alpha` or `releases/beta/3-alpha` because the negative pattern `!releases/**-alpha` follows the positive pattern. + +```yaml +on: + pull_request: + branches: + - 'releases/**' + - '!releases/**-alpha' +``` From 03d7ddef156443dc670755cb0f2513e9a1423d9c Mon Sep 17 00:00:00 2001 From: hubwriter Date: Thu, 18 Jul 2024 08:53:33 +0100 Subject: [PATCH 2/3] Style guide: add advice for in-article links (#51678) --- .../contributing/style-guide-and-content-model/style-guide.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/content/contributing/style-guide-and-content-model/style-guide.md b/content/contributing/style-guide-and-content-model/style-guide.md index 53d0c4420ab0..1e0dda5831f4 100644 --- a/content/contributing/style-guide-and-content-model/style-guide.md +++ b/content/contributing/style-guide-and-content-model/style-guide.md @@ -577,6 +577,7 @@ Links must be consistent, accessible to as many people as possible, translatable Some best practices for using links: * Links should be meaningful and provide high value to the user’s journey. Link out thoughtfully. * Do not repeat the same link more than once in the same article. +* Consider adding "earlier/later in this article" after a link to a section in the same article. * Do not include the `apiVersion` query parameter in REST links unless you need to link to a specific calendar version of the REST docs. (This should be a rare occurrence.) ### Formatting links @@ -628,7 +629,7 @@ Links to specific sections of articles must be descriptive enough that someone u To link to a specific header in the same article, use this format: ```markdown -For more information, see "[HEADER TITLE](#HEADER-TITLE)." +For more information, see "[HEADER TITLE](#HEADER-TITLE)," later in this article. ``` Same-page section links do **not** work with `AUTOTITLE`. Instead, you must type out the full header text. From 85c233c14d2e459614d655dbec4de29457598b79 Mon Sep 17 00:00:00 2001 From: docs-bot <77750099+docs-bot@users.noreply.github.com> Date: Thu, 18 Jul 2024 02:17:29 -0700 Subject: [PATCH 3/3] Sync secret scanning data (#51681) --- src/secret-scanning/lib/config.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/secret-scanning/lib/config.json b/src/secret-scanning/lib/config.json index 25b4f4677bc5..14eed04e33c1 100644 --- a/src/secret-scanning/lib/config.json +++ b/src/secret-scanning/lib/config.json @@ -1,3 +1,3 @@ { - "sha": "c12cbb3c9f1ceac94e0c6375610e92a964b9b83e" + "sha": "18b9c026ea92723ec30584a00a0a4dd4fcbf1aec" } \ No newline at end of file