Repo sync

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
 

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.<pull_request|pull_request_target>.<branches|branches-ignore>`
 
-{% 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.<branches|tags|branches-ignore|tags-ignore>`
 
-{% 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.<push|pull_request|pull_request_target>.<paths|paths-ignore>`
 
-{% 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`
 

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.

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)."

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.*
+```

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.*
+```

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'
+```