From fe1dfd917f3cbdb9b82a5bfe9783ff9e25a3b179 Mon Sep 17 00:00:00 2001 From: Sarah Edwards Date: Tue, 25 Jan 2022 14:25:13 -0800 Subject: [PATCH] Split 'Events that trigger workflows' into two articles (#24392) --- .../events-that-trigger-workflows.md | 188 +-------------- .../using-workflows/triggering-a-workflow.md | 227 ++++++++++++++++-- .../workflow-syntax-for-github-actions.md | 37 +-- .../section-triggering-a-workflow-paths.md | 2 +- .../github-actions/actions-activity-types.md | 22 ++ .../github-actions/actions-filters.md | 11 + .../github-actions/actions-multiple-types.md | 18 ++ .../github-actions/actions-on-examples.md | 66 +---- .../github-actions/on-multiple-example.md | 7 + .../github-actions/on-single-example.md | 5 + .../workflow-dispatch-inputs.md | 34 +++ 11 files changed, 319 insertions(+), 298 deletions(-) create mode 100644 data/reusables/github-actions/actions-activity-types.md create mode 100644 data/reusables/github-actions/actions-filters.md create mode 100644 data/reusables/github-actions/actions-multiple-types.md create mode 100644 data/reusables/github-actions/on-multiple-example.md create mode 100644 data/reusables/github-actions/on-single-example.md create mode 100644 data/reusables/github-actions/workflow-dispatch-inputs.md diff --git a/content/actions/using-workflows/events-that-trigger-workflows.md b/content/actions/using-workflows/events-that-trigger-workflows.md index a1b052e58e..e298fe3832 100644 --- a/content/actions/using-workflows/events-that-trigger-workflows.md +++ b/content/actions/using-workflows/events-that-trigger-workflows.md @@ -16,193 +16,9 @@ versions: shortTitle: Events that trigger workflows --- -{% data reusables.actions.enterprise-beta %} -{% data reusables.actions.enterprise-github-hosted-runners %} +## About events that trigger workflows -## About workflow triggers - -Workflow triggers are events that cause a workflow to run. These events can be: - -- Events that occur in your workflow's repository -- Events that occur outside of {% data variables.product.product_name %} and trigger a `repository_dispatch` event on {% data variables.product.product_name %} -- Scheduled times -- Manual - -For example, you can configure your workflow to run when a push is made to the default branch of your repository, when a release is created, or when an issue is opened. - -Workflow triggers are defined with the `on` key. For more information, see "[Workflow syntax for {% data variables.product.prodname_actions %}](/articles/workflow-syntax-for-github-actions#on)." - -The following steps occur to trigger a workflow run: - -1. An event occurs on your repository. The event has an associated commit SHA and Git ref. -1. {% data variables.product.product_name %} searches the `.github/workflows` directory in your repository for workflow files that are present in the associated commit SHA or Git ref of the event. - -1. A workflow run is triggered for any workflows that have `on:` values that match the triggering event. Some events also require the workflow file to be present on the default branch of the repository in order to run. - - Each workflow run will use the version of the workflow that is present in the associated commit SHA or Git ref of the event. When a workflow runs, {% data variables.product.product_name %} sets the `GITHUB_SHA` (commit SHA) and `GITHUB_REF` (Git ref) environment variables in the runner environment. For more information, see "[Using environment variables](/actions/automating-your-workflow-with-github-actions/using-environment-variables)." - -### Triggering a workflow from a workflow - -{% data reusables.github-actions.actions-do-not-trigger-workflows %} For more information, see "[Authenticating with the GITHUB_TOKEN](/actions/configuring-and-managing-workflows/authenticating-with-the-github_token)." - -If you do want to trigger a workflow from within a workflow run, you can use a personal access token instead of `GITHUB_TOKEN` to trigger events that require a token. You'll need to create a personal access token and store it as a secret. To minimize your {% data variables.product.prodname_actions %} usage costs, ensure that you don't create recursive or unintended workflow runs. For more information about creating a personal access token, see "[Creating a personal access token](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)." For more information about storing a personal access token as a secret, see "[Creating and storing encrypted secrets](/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets)." - -For example, the following workflow uses a personal access token (stored as a secret called `MY_TOKEN`) to add a label to an issue via {% data variables.product.prodname_cli %}. Any workflows that run when a label is added will run once this step is performed. - -```yaml -on: - issues: - types: - - opened - -jobs: - label_issue: - runs-on: ubuntu-latest - steps: - - env: - GITHUB_TOKEN: {% raw %}${{ secrets.MY_TOKEN }}{% endraw %} - ISSUE_URL: {% raw %}${{ github.event.issue.html_url }}{% endraw %} - run: | - gh issue edit $ISSUE_URL --add-label "triage" -``` - -Conversely, the following workflow uses `GITHUB_TOKEN` to add a label to an issue. It will not trigger any workflows that run when a label is added. - -```yaml -on: - issues: - types: - - opened - -jobs: - label_issue: - runs-on: ubuntu-latest - steps: - - env: - GITHUB_TOKEN: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %} - ISSUE_URL: {% raw %}${{ github.event.issue.html_url }}{% endraw %} - run: | - gh issue edit $ISSUE_URL --add-label "triage" -``` - -## Using events to trigger workflows - -Use the `on` key to specify what events trigger your workflow. For more information about events you can use, see "[Available events](#available-events)" below. - -{% data reusables.github-actions.actions-on-examples %} - -## Using event information - -Information about the event that triggered a workflow run is available in the `github.event` context. The properties in the `github.event` context depend on the type of event that triggered the workflow. For example, a workflow triggered when an issue is labeled would have information about the issue and label. - -### Viewing all properties of an event - -Reference the webhook event documentation for common properties and example payloads. For more information, see "[Webhook events and payloads](/developers/webhooks-and-events/webhooks/webhook-events-and-payloads)." - -You can also print the entire `github.event` context to see what properties are available for the event that triggered your workflow: - -```yaml -jobs: - print_context: - runs-on: ubuntu-latest - steps: - - env: - EVENT_CONTEXT: {% raw %}${{ toJSON(github.event) }}{% endraw %} - run: | - echo $EVENT_CONTEXT -``` - -### Accessing and using event properties - -You can use the `github.event` context in your workflow. For example, the following workflow runs when a pull request that changes `package*.json`, `.github/CODEOWNERS`, or `.github/workflows/**` is opened. If the pull request author (`github.event.pull_request.user.login`) is not `octobot` or `dependabot[bot]`, then the workflow uses the {% data variables.product.prodname_cli %} to label and comment on the pull request (`github.event.pull_request.number`). - -```yaml -on: - pull_request: - types: - - opened - paths: - - '.github/workflows/**' - - '.github/CODEOWNERS' - - 'package*.json' - -jobs: - triage: - if: >- - github.event.pull_request.user.login != 'octobot' && - github.event.pull_request.user.login != 'dependabot[bot]' - runs-on: ubuntu-latest - steps: - - name: "Comment about changes we can't accept" - env: - GITHUB_TOKEN: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %} - PR: {% raw %}${{ github.event.pull_request.html_url }}{% endraw %} - run: | - gh pr edit $PR --add-label 'invalid' - gh pr comment $PR --body 'It looks like you edited `package*.json`, `.github/CODEOWNERS`, or `.github/workflows/**`. We do not allow contributions to these files. Please review our [contributing guidelines](https://github.com/octo-org/octo-repo/blob/main/CONTRIBUTING.md) for what contributions are accepted.' -``` - -For more information about contexts, see "[Contexts](/actions/learn-github-actions/contexts)." For more information about event payloads, see "[Webhook events and payloads](/developers/webhooks-and-events/webhooks/webhook-events-and-payloads)." - -## Further controlling how your workflow will run - -If you want more granular control than events, event activity types, or event filters provide, you can use conditionals{% ifversion fpt or ghae or ghes > 3.1 or ghec %} and environments{% endif %} to control whether individual jobs or steps in your workflow will run. - -### Using conditionals - -You can use conditionals to further control whether jobs or steps in your workflow will run. For example, if you want the workflow to run when a specific label is added to an issue, you can trigger on the `issues labeled` event activity type and use a conditional to check what label triggered the workflow. The following workflow will run when any label is added to an issue in the workflow's repository, but the `run_if_label_matches` job will only execute if the label is named `bug`. - -```yaml -on: - issues: - types: - - labeled - -jobs: - run_if_label_matches: - if: github.event.label.name == 'bug' - runs-on: ubuntu-latest - steps: - - run: echo 'The label was bug' -``` - -For more information, see "[Expressions](/actions/learn-github-actions/expressions)." - -{% ifversion fpt or ghae or ghes > 3.1 or ghec %} -### Using environments to manually trigger workflow jobs - -If you want to manually trigger a specific job in a workflow, you can use an environment that requires approval from a specific team or user. First, configure an environment with required reviewers. For more information, see "[Using environments for deployment](/actions/deployment/targeting-different-environments/using-environments-for-deployment)." Then, reference the environment name in a job in your workflow using the `environment:` key. Any job referencing the environment will not run until at least one reviewer approves the job. - -For example, the following workflow will run whenever there is a push to main. The `build` job will always run. The `publish` job will only run after the `build` job successfully completes (due to `needs: [build]`) and after all of the rules (including required reviewers) for the environment called `production` pass (due to `environment: production`). - -```yaml -on: - push: - branches: - - main - -jobs: - build: - runs-on: ubuntu-latest - steps: - - name: build - echo 'building' - - publish: - needs: [build] - runs-on: ubuntu-latest - environment: production - steps: - - name: publish - echo 'publishing' -``` - -{% note %} - -{% data reusables.gated-features.environments %} - -{% endnote %} -{% endif %} +Workflow triggers are events that cause a workflow to run. For more information about how to use workflow triggers, see "[Triggering a workflow](/actions/using-workflows/triggering-a-workflow)." ## Available events diff --git a/content/actions/using-workflows/triggering-a-workflow.md b/content/actions/using-workflows/triggering-a-workflow.md index 232b23ef14..39b74603f1 100644 --- a/content/actions/using-workflows/triggering-a-workflow.md +++ b/content/actions/using-workflows/triggering-a-workflow.md @@ -12,36 +12,235 @@ topics: - Workflows - CI - CD -miniTocMaxHeadingLevel: 4 +miniTocMaxHeadingLevel: 3 --- {% data reusables.actions.enterprise-beta %} {% data reusables.actions.enterprise-github-hosted-runners %} -## Overview +## About workflow triggers -{% data reusables.actions.workflows.section-triggering-a-workflow %} +Workflow triggers are events that cause a workflow to run. These events can be: -## Defining event types +- Events that occur in your workflow's repository +- Events that occur outside of {% data variables.product.product_name %} and trigger a `repository_dispatch` event on {% data variables.product.product_name %} +- Scheduled times +- Manual -{% data reusables.actions.workflows.section-triggering-a-workflow-types %} +For example, you can configure your workflow to run when a push is made to the default branch of your repository, when a release is created, or when an issue is opened. -## Targeting specific branches +Workflow triggers are defined with the `on` key. For more information, see "[Workflow syntax for {% data variables.product.prodname_actions %}](/articles/workflow-syntax-for-github-actions#on)." + +The following steps occur to trigger a workflow run: + +1. An event occurs on your repository. The event has an associated commit SHA and Git ref. +1. {% data variables.product.product_name %} searches the `.github/workflows` directory in your repository for workflow files that are present in the associated commit SHA or Git ref of the event. +1. A workflow run is triggered for any workflows that have `on:` values that match the triggering event. Some events also require the workflow file to be present on the default branch of the repository in order to run. + + Each workflow run will use the version of the workflow that is present in the associated commit SHA or Git ref of the event. When a workflow runs, {% data variables.product.product_name %} sets the `GITHUB_SHA` (commit SHA) and `GITHUB_REF` (Git ref) environment variables in the runner environment. For more information, see "[Using environment variables](/actions/automating-your-workflow-with-github-actions/using-environment-variables)." + +### Triggering a workflow from a workflow + +{% data reusables.github-actions.actions-do-not-trigger-workflows %} For more information, see "[Authenticating with the GITHUB_TOKEN](/actions/configuring-and-managing-workflows/authenticating-with-the-github_token)." + +If you do want to trigger a workflow from within a workflow run, you can use a personal access token instead of `GITHUB_TOKEN` to trigger events that require a token. You'll need to create a personal access token and store it as a secret. To minimize your {% data variables.product.prodname_actions %} usage costs, ensure that you don't create recursive or unintended workflow runs. For more information about creating a personal access token, see "[Creating a personal access token](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)." For more information about storing a personal access token as a secret, see "[Creating and storing encrypted secrets](/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets)." + +For example, the following workflow uses a personal access token (stored as a secret called `MY_TOKEN`) to add a label to an issue via {% data variables.product.prodname_cli %}. Any workflows that run when a label is added will run once this step is performed. + +```yaml +on: + issues: + types: + - opened + +jobs: + label_issue: + runs-on: ubuntu-latest + steps: + - env: + GITHUB_TOKEN: {% raw %}${{ secrets.MY_TOKEN }}{% endraw %} + ISSUE_URL: {% raw %}${{ github.event.issue.html_url }}{% endraw %} + run: | + gh issue edit $ISSUE_URL --add-label "triage" +``` + +Conversely, the following workflow uses `GITHUB_TOKEN` to add a label to an issue. It will not trigger any workflows that run when a label is added. + +```yaml +on: + issues: + types: + - opened + +jobs: + label_issue: + runs-on: ubuntu-latest + steps: + - env: + GITHUB_TOKEN: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %} + ISSUE_URL: {% raw %}${{ github.event.issue.html_url }}{% endraw %} + run: | + gh issue edit $ISSUE_URL --add-label "triage" +``` + +## Using events to trigger workflows + +Use the `on` key to specify what events trigger your workflow. For more information about events you can use, see "[Events that trigger workflows](/actions/using-workflows/events-that-trigger-workflows)." + +### Using a single event + +{% data reusables.github-actions.on-single-example %} + +### Using multiple events + +{% data reusables.github-actions.on-multiple-example %} + +### Using activity types and filters with multiple events + +You can use activity types and filters to further control when your workflow will run. For more information, see [Using event activity types](#using-event-activity-types) and [Using filters](#using-filters). {% data reusables.github-actions.actions-multiple-types %} + +## Using event activity types + +{% data reusables.github-actions.actions-activity-types %} + +## Using filters + +{% data reusables.github-actions.actions-filters %} + +### Using filters to target specific branches for pull request events {% data reusables.actions.workflows.section-triggering-a-workflow-branches %} -## Running on specific branches or tags +### Using filters to target specific branches or tags for push events {% data reusables.actions.workflows.section-run-on-specific-branches-or-tags %} -## Specifying which branches the workflow can run on - -{% data reusables.actions.workflows.section-specifying-branches %} - -## Using specific file paths +### Using filters to target specific paths for pull request or push events {% data reusables.actions.workflows.section-triggering-a-workflow-paths %} -## Using a schedule +### Using filters to target specific branches for workflow run events -{% data reusables.actions.workflows.section-triggering-a-workflow-schedule %} +{% data reusables.actions.workflows.section-specifying-branches %} + +## Defining inputs for manually triggered workflows + +{% data reusables.github-actions.workflow-dispatch-inputs %} + +## Using event information + +Information about the event that triggered a workflow run is available in the `github.event` context. The properties in the `github.event` context depend on the type of event that triggered the workflow. For example, a workflow triggered when an issue is labeled would have information about the issue and label. + +### Viewing all properties of an event + +Reference the webhook event documentation for common properties and example payloads. For more information, see "[Webhook events and payloads](/developers/webhooks-and-events/webhooks/webhook-events-and-payloads)." + +You can also print the entire `github.event` context to see what properties are available for the event that triggered your workflow: + +```yaml +jobs: + print_context: + runs-on: ubuntu-latest + steps: + - env: + EVENT_CONTEXT: {% raw %}${{ toJSON(github.event) }}{% endraw %} + run: | + echo $EVENT_CONTEXT +``` + +### Accessing and using event properties + +You can use the `github.event` context in your workflow. For example, the following workflow runs when a pull request that changes `package*.json`, `.github/CODEOWNERS`, or `.github/workflows/**` is opened. If the pull request author (`github.event.pull_request.user.login`) is not `octobot` or `dependabot[bot]`, then the workflow uses the {% data variables.product.prodname_cli %} to label and comment on the pull request (`github.event.pull_request.number`). + +```yaml +on: + pull_request: + types: + - opened + paths: + - '.github/workflows/**' + - '.github/CODEOWNERS' + - 'package*.json' + +jobs: + triage: + if: >- + github.event.pull_request.user.login != 'octobot' && + github.event.pull_request.user.login != 'dependabot[bot]' + runs-on: ubuntu-latest + steps: + - name: "Comment about changes we can't accept" + env: + GITHUB_TOKEN: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %} + PR: {% raw %}${{ github.event.pull_request.html_url }}{% endraw %} + run: | + gh pr edit $PR --add-label 'invalid' + gh pr comment $PR --body 'It looks like you edited `package*.json`, `.github/CODEOWNERS`, or `.github/workflows/**`. We do not allow contributions to these files. Please review our [contributing guidelines](https://github.com/octo-org/octo-repo/blob/main/CONTRIBUTING.md) for what contributions are accepted.' +``` + +For more information about contexts, see "[Contexts](/actions/learn-github-actions/contexts)." For more information about event payloads, see "[Webhook events and payloads](/developers/webhooks-and-events/webhooks/webhook-events-and-payloads)." + +## Further controlling how your workflow will run + +If you want more granular control than events, event activity types, or event filters provide, you can use conditionals{% ifversion fpt or ghae or ghes > 3.1 or ghec %} and environments{% endif %} to control whether individual jobs or steps in your workflow will run. + +### Using conditionals + +You can use conditionals to further control whether jobs or steps in your workflow will run. For example, if you want the workflow to run when a specific label is added to an issue, you can trigger on the `issues labeled` event activity type and use a conditional to check what label triggered the workflow. The following workflow will run when any label is added to an issue in the workflow's repository, but the `run_if_label_matches` job will only execute if the label is named `bug`. + +```yaml +on: + issues: + types: + - labeled + +jobs: + run_if_label_matches: + if: github.event.label.name == 'bug' + runs-on: ubuntu-latest + steps: + - run: echo 'The label was bug' +``` + +For more information, see "[Expressions](/actions/learn-github-actions/expressions)." + +{% ifversion fpt or ghae or ghes > 3.1 or ghec %} + +### Using environments to manually trigger workflow jobs + +If you want to manually trigger a specific job in a workflow, you can use an environment that requires approval from a specific team or user. First, configure an environment with required reviewers. For more information, see "[Using environments for deployment](/actions/deployment/targeting-different-environments/using-environments-for-deployment)." Then, reference the environment name in a job in your workflow using the `environment:` key. Any job referencing the environment will not run until at least one reviewer approves the job. + +For example, the following workflow will run whenever there is a push to main. The `build` job will always run. The `publish` job will only run after the `build` job successfully completes (due to `needs: [build]`) and after all of the rules (including required reviewers) for the environment called `production` pass (due to `environment: production`). + +```yaml +on: + push: + branches: + - main + +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: build + echo 'building' + + publish: + needs: [build] + runs-on: ubuntu-latest + environment: production + steps: + - name: publish + echo 'publishing' +``` + +{% note %} + +{% data reusables.gated-features.environments %} + +{% endnote %} +{% endif %} + +## Available events + +For a full list of available events, see "[Events that trigger workflows](/actions/using-workflows/events-that-trigger-workflows)." 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 8873f11f68..37cb001e82 100644 --- a/content/actions/using-workflows/workflow-syntax-for-github-actions.md +++ b/content/actions/using-workflows/workflow-syntax-for-github-actions.md @@ -171,42 +171,7 @@ A boolean specifying whether the secret must be supplied. ## `on.workflow_dispatch.inputs` -When using the `workflow_dispatch` event, you can optionally specify inputs that are passed to the workflow. - -The triggered workflow receives the inputs in the `github.event.inputs` context. For more information, see "[Contexts](/actions/learn-github-actions/contexts#github-context)." - -### Example -```yaml -on: - workflow_dispatch: - inputs: - logLevel: - description: 'Log level' - required: true - default: 'warning' {% ifversion fpt or ghec or ghes > 3.3 or ghae-issue-5511 %} - type: choice - options: - - info - - warning - - debug {% endif %} - tags: - description: 'Test scenario tags' - required: false {% ifversion fpt or ghec or ghes > 3.3 or ghae-issue-5511 %} - type: boolean - environment: - description: 'Environment to run tests against' - type: environment - required: true {% endif %} - -jobs: - print-tag: - runs-on: ubuntu-latest - - steps: - - name: Print the input tag to STDOUT - run: echo {% raw %} The tag is ${{ github.event.inputs.tag }} {% endraw %} -``` - +{% data reusables.github-actions.workflow-dispatch-inputs %} {% ifversion fpt or ghes > 3.1 or ghae or ghec %} ## `permissions` diff --git a/data/reusables/actions/workflows/section-triggering-a-workflow-paths.md b/data/reusables/actions/workflows/section-triggering-a-workflow-paths.md index 93b62fddbf..407bbeb555 100644 --- a/data/reusables/actions/workflows/section-triggering-a-workflow-paths.md +++ b/data/reusables/actions/workflows/section-triggering-a-workflow-paths.md @@ -52,7 +52,7 @@ on: - '!sub-project/docs/**' ``` -### Git diff comparisons +#### Git diff comparisons {% note %} diff --git a/data/reusables/github-actions/actions-activity-types.md b/data/reusables/github-actions/actions-activity-types.md new file mode 100644 index 0000000000..9c5b6d55c4 --- /dev/null +++ b/data/reusables/github-actions/actions-activity-types.md @@ -0,0 +1,22 @@ +Some events have activity types that give you more control over when your workflow should run. Use `on..types` to define the type of event activity that will trigger a workflow run. + +For example, the `issue_comment` event has the `created`, `edited`, and `deleted` activity types. If your workflow triggers on the `label` event, it will run whenever a label is created, edited, or deleted. If you specify the `created` activity type for the `label` event, your workflow will run when a label is created but not when a label is edited or deleted. + +```yaml +on: + label: + types: + - created +``` + +If you specify multiple activity types, only one of those event activity types needs to occur to trigger your workflow. If multiple triggering event activity types for your workflow occur at the same time, multiple workflow runs will be triggered. For example, the following workflow triggers when an issue is opened or labeled. If an issue with two labels is opened, three workflow runs will start: one for the issue opened event and two for the two issue labeled events. + +```yaml +on: + issue: + types: + - opened + - labeled +``` + +For more information about each event and their activity types, see "[Events that trigger workflows](/actions/using-workflows/events-that-trigger-workflows)." diff --git a/data/reusables/github-actions/actions-filters.md b/data/reusables/github-actions/actions-filters.md new file mode 100644 index 0000000000..549ef0190e --- /dev/null +++ b/data/reusables/github-actions/actions-filters.md @@ -0,0 +1,11 @@ +Some events have filters that give you more control over when your workflow should run. + +For example, the `push` event has a `branches` filter that causes your workflow to run only when a push to a branch that matches the `branches` filter occurs, instead of when any push occurs. + +```yaml +on: + push: + branches: + - main + - 'releases/**' +``` \ No newline at end of file diff --git a/data/reusables/github-actions/actions-multiple-types.md b/data/reusables/github-actions/actions-multiple-types.md new file mode 100644 index 0000000000..0a904faa5c --- /dev/null +++ b/data/reusables/github-actions/actions-multiple-types.md @@ -0,0 +1,18 @@ +If you specify activity types or filters for an event and your workflow triggers on multiple events, you must configure each event separately. You must append a colon (`:`) to all events, including events without configuration. + +For example, a workflow with the following `on` value will run when: + +- A label is created +- A push is made to the `main` branch in the repository +- A push is made to a {% data variables.product.prodname_pages %}-enabled branch + +```yaml +on: + label: + types: + - created + push: + branches: + - main + page_build: +``` diff --git a/data/reusables/github-actions/actions-on-examples.md b/data/reusables/github-actions/actions-on-examples.md index 9590cce8e5..26d4a25747 100644 --- a/data/reusables/github-actions/actions-on-examples.md +++ b/data/reusables/github-actions/actions-on-examples.md @@ -1,75 +1,19 @@ ### Using a single event -For example, a workflow with the following `on` value will run when a push is made to any branch in the workflow's repository: - -```yaml -on: push -``` +{% data reusables.github-actions.on-single-example %} ### Using multiple events -You can specify a single event or multiple events. For example, a workflow with the following `on` value will run when a push is made to any branch in the repository or when someone forks the repository: - -```yaml -on: [push, fork] -``` - -If you specify multiple events, only one of those events needs to occur to trigger your workflow. If multiple triggering events for your workflow occur at the same time, multiple workflow runs will be triggered. +{% data reusables.github-actions.on-multiple-example %} ### Using activity types -Some events have activity types that give you more control over when your workflow should run. - -For example, the `issue_comment` event has the `created`, `edited`, and `deleted` activity types. If your workflow triggers on the `label` event, it will run whenever a label is created, edited, or deleted. If you specify the `created` activity type for the `label` event, your workflow will run when a label is created but not when a label is edited or deleted. - -```yaml -on: - label: - types: - - created -``` - -If you specify multiple activity types, only one of those event activity types needs to occur to trigger your workflow. If multiple triggering event activity types for your workflow occur at the same time, multiple workflow runs will be triggered. For example, the following workflow triggers when an issue is opened or labeled. If an issue with two labels is opened, three workflow runs will start: one for the issue opened event and two for the two issue labeled events. - -```yaml -on: - issue: - types: - - opened - - labeled -``` +{% data reusables.github-actions.actions-activity-types %} ### Using filters -Some events have filters that give you more control over when your workflow should run. - -For example, the `push` event has a `branches` filter that causes your workflow to run only when a push to a branch that matches the `branches` filter occurs, instead of when any push occurs. - -```yaml -on: - push: - branches: - - main - - 'releases/**' -``` +{% data reusables.github-actions.actions-filters %} ### Using activity types and filters with multiple events -If you specify activity types or filters for an event and your workflow triggers on multiple events, you must configure each event separately. You must append a colon (`:`) to all events, including events without configuration. - -For example, a workflow with the following `on` value will run when: - -- A label is created -- A push is made to the `main` branch in the repository -- A push is made to a {% data variables.product.prodname_pages %}-enabled branch - -```yaml -on: - label: - types: - - created - push: - branches: - - main - page_build: -``` \ No newline at end of file +{% data reusables.github-actions.actions-multiple-types %} \ No newline at end of file diff --git a/data/reusables/github-actions/on-multiple-example.md b/data/reusables/github-actions/on-multiple-example.md new file mode 100644 index 0000000000..66a7708123 --- /dev/null +++ b/data/reusables/github-actions/on-multiple-example.md @@ -0,0 +1,7 @@ +You can specify a single event or multiple events. For example, a workflow with the following `on` value will run when a push is made to any branch in the repository or when someone forks the repository: + +```yaml +on: [push, fork] +``` + +If you specify multiple events, only one of those events needs to occur to trigger your workflow. If multiple triggering events for your workflow occur at the same time, multiple workflow runs will be triggered. diff --git a/data/reusables/github-actions/on-single-example.md b/data/reusables/github-actions/on-single-example.md new file mode 100644 index 0000000000..b8c7046c3e --- /dev/null +++ b/data/reusables/github-actions/on-single-example.md @@ -0,0 +1,5 @@ +For example, a workflow with the following `on` value will run when a push is made to any branch in the workflow's repository: + +```yaml +on: push +``` diff --git a/data/reusables/github-actions/workflow-dispatch-inputs.md b/data/reusables/github-actions/workflow-dispatch-inputs.md new file mode 100644 index 0000000000..f7de2293a5 --- /dev/null +++ b/data/reusables/github-actions/workflow-dispatch-inputs.md @@ -0,0 +1,34 @@ +When using the `workflow_dispatch` event, you can optionally specify inputs that are passed to the workflow. + +The triggered workflow receives the inputs in the `github.event.inputs` context. For more information, see "[Contexts](/actions/learn-github-actions/contexts#github-context)." + +```yaml +on: + workflow_dispatch: + inputs: + logLevel: + description: 'Log level' + required: true + default: 'warning' {% ifversion fpt or ghec or ghes > 3.3 or ghae-issue-5511 %} + type: choice + options: + - info + - warning + - debug {% endif %} + tags: + description: 'Test scenario tags' + required: false {% ifversion fpt or ghec or ghes > 3.3 or ghae-issue-5511 %} + type: boolean + environment: + description: 'Environment to run tests against' + type: environment + required: true {% endif %} + +jobs: + print-tag: + runs-on: ubuntu-latest + + steps: + - name: Print the input tag to STDOUT + run: echo {% raw %} The tag is ${{ github.event.inputs.tag }} {% endraw %} +```