docs: add example YAML for workflow_dispatch

[bnb]

Why:

This page explains workflow_dispatch - it shows how to actually use the UI, but it's easy to land here wanting to know how to fully use it both in terms of UI and code. This adds a simple example of the syntax for how to use it.

What's being changed:

Adding a H3 (aligned with the other headings) and a small code example.

Check off the following:

• All of the tests are passing.
• I have reviewed my changes in staging.
• For content changes, I have reviewed the localization checklist
• For content changes, I have reviewed the Content style guide for GitHub Docs.

[welcome]

Thanks for opening this pull request! A GitHub docs team member should be by to give feedback soon. In the meantime, please check out the contributing guidelines.

[janiceilene]

Thanks for opening a PR 👍 Please fill out the pull request template and we'll get this up for review!

[bnb]

Did my best with the review of localization and content style, apologies if I missed anything - happy to make whatever changes necessary if I missed something 🙇🏻

[janiceilene]

Thanks @bnb Can you fill out the Why and the What's being changed? in your original comment in this PR? That'll help us to triage and find the best reviewers for your pull request. Thank you so much!

[bnb]

My apologies @janiceilene, should be fixed now, I totally spaced not once but twice. Thank you for being patient with me 🙇🏻

[janiceilene]

Thank you so much @bnb! I think the format of the PR template wasn't the best. The big warning at the top made it super easy to bypass completely. I tweaked it this morning, so hopefully it's a bit more welcoming! I'll get this triaged for review 💝

[rachmari]

@bnb thank you for pointing out this missing information in the docs! 🙌 I think the addition you made definitely makes sense, but the article in this section are all geared toward how to accomplish something after the workflow is created. We may change that in the future, and your PR definitely prompted me to rethink that model.

I had a suggestion that wouldn't change the model we currently have but would require some additional changes. Let me know what you think! 💚 💭

[rachmari]

I agree that folks landing on this page might want to know about both the workflow configuration and how to use the UI, but we do already have an example workflow for this case on another page. Both sections "Running a workflow using the REST API" and "Running a workflow on GitHub" require the workflow to be configured for the workflow_dispatch, which is why we've included the paragraph linking to the events at the top of the article
https://github.com/github/docs/pull/358/files#diff-0d421d891ef5301f3a44801c5f65c183d09e5ffb890dfc8c95ea68f29311a402R13

But I realize that the link we include up there doesn't directly link to the workflow_dispatch event. 😬 It should.

To address the visibility of that link, maybe we can create a new section header for the information linking to the workflow_dispatch event description. So you could replace the paragraph at the top with:

### Configuring a workflow to run manually

To run a workflow manually, the workflow must be configured to run on the `workflow_dispatch` event. For more information about configuring the `workflow_dispatch` event, see "[Events that trigger workflows](/actions/reference/events-that-trigger-workflows#workflow_dispatch)."

We could then also include your example here as an alternate example on this page: https://docs.github.com/en/free-pro-team@latest/actions/reference/events-that-trigger-workflows#example-workflow-configuration

For example:

Example

on: workflow_dispatch

Example configuration with inputs

This example defines the name and home inputs and prints them using the github.event.inputs.name and github.event.inputs.home contexts. If a name isn't provided, the default value 'Mona the Octocat' is printed.

name: Manually triggered workflow
on:
  workflow_dispatch:
    inputs:
      name:
        description: 'Person to greet'
        required: true
        default: 'Mona the Octocat'
      home:
        description: 'location'
        required: false

jobs:
  say_hello:
    runs-on: ubuntu-latest
    steps:
    - run: |
        echo "Hello ${{ github.event.inputs.name }}!"
        echo "- in ${{ github.event.inputs.home }}!"

[bnb]

This makes sense. Would you like me to do that work in this PR, create a new one, or would it be something y'all would want to do yourselves?

[rachmari]

@bnb feel free to update this PR if you'd like to. Our team probably won't be able to get to this for a bit, so any contributions you make here would be super helpful!

[bnb]

force pushed the changes @rachmari suggested (to the best of my understanding of them) 👍🏻

[rachmari]

@bnb this update looks great! I just had a few copy edit suggestions, but once those are fixed up I'll get this merged. 🚢 🚀

[rachmari]

@bnb thanks! That was the last thing I needed. I'll get this shipped right now. 🚢 🚢 🚢

[github-actions]

Thanks very much for contributing! Your pull request has been merged 🎉 You should see your changes appear on the site in approximately 24 hours.

[GokhanAydinnn]

11 nn