Update the Skills course for Actions (#74)

* Start updating the course

* Remove boilerplate comments

* Remove boilerplate comments from readme

* More clarifications

* More clarifications

* Fix typo

* Fix typo

* Update .github/steps/1-create-a-workflow.md

* Update .github/steps/2-add-a-job.md

* Update .github/steps/3-add-actions.md

Co-authored-by: Felicity Chapman <felicitymay@github.com>

* Update .github/steps/5-trigger.md

Co-authored-by: Felicity Chapman <felicitymay@github.com>

* Update .github/steps/X-finish.md

Co-authored-by: Felicity Chapman <felicitymay@github.com>

* Update 3-add-actions.md

---------

Co-authored-by: Felicity Chapman <felicitymay@github.com>

.github/steps/0-welcome.md

@@ -1 +1 @@
-<!-- readme -->
+<!-- The readme will be displayed. -->

.github/steps/1-create-a-workflow.md

@@ -1,11 +1,3 @@
-<!--
-  <<< Author notes: Step 1 >>>
-  Choose 3-5 steps for your course.
-  The first step is always the hardest, so pick something easy!
-  Link to docs.github.com for further explanations.
-  Encourage users to open new tabs for steps!
--->
-
 ## Step 1: Create a workflow file
 
 _Welcome to "Hello GitHub Actions"! :wave:_
@@ -20,24 +12,30 @@ _Welcome to "Hello GitHub Actions"! :wave:_
 - To read more about workflows, jobs, and events, see "[Understanding GitHub Actions](https://docs.github.com/en/actions/learn-github-actions/understanding-github-actions)".
 - If you want to learn more about the `pull_request` event before using it, see "[pull_request](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#pull_request)".
 
-To get you started, we used actions to go ahead and made a branch and pull request for you.
+To get you started, we ran an Actions workflow in your new repository that, among other things, created a branch for you to work in, called `welcome-workflow`.
 
 ### :keyboard: Activity: Create a workflow file
 
 1. Open a new browser tab, and navigate to this same repository. Then, work on the steps in your second tab while you read the instructions in this tab.
-1. Create a pull request to view all the changes you'll make throughout this course. Click the **Pull Requests** tab, click **New pull request**, set `base: main` and `compare:welcome-workflow`, click **Create pull request**.
+1. Create a pull request. This will contain all of the changes you'll make throughout this part of the course.
+
+   Click the **Pull Requests** tab, click **New pull request**, set `base: main` and `compare:welcome-workflow`, click **Create pull request**, then click **Create pull request** again.
+
 1. Navigate to the **Code** tab.
 1. From the **main** branch dropdown, click on the **welcome-workflow** branch.
 1. Navigate to the `.github/workflows/` folder, then select **Add file** and click on **Create new file**.
-1. In the **Name your file...** field, enter `welcome.yml`.
+1. In the **Name your file** field, enter `welcome.yml`.
 1. Add the following content to the `welcome.yml` file:
-   ```yaml
+
+   ```yaml copy
    name: Post welcome comment
    on:
      pull_request:
        types: [opened]
    permissions:
      pull-requests: write
    ```
-1. To commit your changes, click **Commit new file**.
-1. Wait about 20 seconds for actions to run, then refresh this page (the one you're following instructions from) and an action will automatically close this step and open the next one.
+
+1. To commit your changes, click **Commit changes**.
+1. Type a commit message, select **Commit directly to the welcome-workflow branch** and click **Commit changes**.
+1. Wait about 20 seconds, then refresh this page (the one you're following instructions from). A separate Actions workflow in the repository (not the workflow you created) will run and will automatically replace this contents of this README file with instructions for the next step.

.github/steps/2-add-a-job.md

@@ -1,32 +1,26 @@
-<!--
-  <<< Author notes: Step 2 >>>
-  Start this step by acknowledging the previous step.
-  Define terms and link to docs.github.com.
-  Historic note: The previous course had troubleshooting steps for people not using the GitHub UI.
--->
-
 ## Step 2: Add a job to your workflow file
 
 _Nice work! :tada: You added a workflow file!_
 
-Here's what it means:
+Here's what the entries in the `welcome.yml` file, on the `welcome-workflow` branch, mean:
 
-- `name: Post welcome comment` gives your workflow a name. This name appears on any pull request or in the Actions tab of your repository.
-- `on: pull_request: types: [opened]` indicates that your workflow will execute anytime a pull request opens in your repository.
+- `name: Post welcome comment` gives your workflow a name. This name will appear in the Actions tab of your repository.
+- `on: pull_request: types: [opened]` indicates that your workflow will execute whenever someone opens a pull request in your repository.
 - `permissions` assigns the workflow permissions to operate on the repository
 - `pull-requests: write` gives the workflow permission to write to pull requests. This is needed to create the welcome comment.
 
 Next, we need to specify jobs to run.
 
-**What is a _job_?**: A job is a set of steps in a workflow that execute on the same runner (a runner is a server that runs your workflows when triggered). Workflows have jobs, and jobs have steps. Steps are executed in order and are dependent on each other. We'll add steps in the next step of this exercise. To read more about jobs, see "[Jobs](https://docs.github.com/en/actions/learn-github-actions/understanding-github-actions#jobs)".
+**What is a _job_?**: A job is a set of steps in a workflow that execute on the same runner (a runner is a server that runs your workflows when triggered). Workflows have jobs, and jobs have steps. Steps are executed in order and are dependent on each other. You'll add steps to your workflow later in the course. To read more about jobs, see "[Jobs](https://docs.github.com/en/actions/learn-github-actions/understanding-github-actions#jobs)".
 
-In this step of our exercise, we will add a "build" job. We will specify `ubuntu-latest` as the fastest and cheapest job runner available. If you want to read more about why we'll use that runner, see the code explanation for the line `runs-on: ubuntu-latest` in the "[Understanding the workflow file](https://docs.github.com/en/actions/learn-github-actions/understanding-github-actions#understanding-the-workflow-file)" article.
+In the following activity, you'll add a "build" job to your workflow. You'll specify `ubuntu-latest` as the fastest, and cheapest, job runner available. If you want to read more about why we'll use that runner, see the code explanation for the line `runs-on: ubuntu-latest` in the "[Understanding the workflow file](https://docs.github.com/en/actions/learn-github-actions/understanding-github-actions#understanding-the-workflow-file)" article.
 
 ### :keyboard: Activity: Add a job to your workflow file
 
-1. Open your `welcome.yml` file.
-2. Update the contents of the file to:
-   ```yaml
+1. In a separate browser tab, make sure you are on the `welcome-workflow` branch and open your `.github/workflows/welcome.yml` file.
+1. Edit the file and update its contents to:
+
+   ```yaml copy
    name: Post welcome comment
    on:
      pull_request:
@@ -38,6 +32,7 @@ In this step of our exercise, we will add a "build" job. We will specify `ubuntu
        name: Post welcome comment
        runs-on: ubuntu-latest
    ```
-3. Click **Commit changes...** in the top right of the workflow editor.
-4. Type your commit message and commit your changes directly to your branch.
-5. Wait about 20 seconds for actions to run, then refresh this page (the one you're following instructions from) and an action will automatically close this step and open the next one.
+
+1. Click **Commit changes** in the top right of the workflow editor.
+1. Type a commit message and commit your changes directly to the `welcome-workflow` branch.
+1. Wait about 20 seconds, then refresh this page (the one you're following instructions from). Another workflow will run and will replace this content with instructions for the next step.

.github/steps/3-add-actions.md

@@ -1,24 +1,21 @@
-<!--
-  <<< Author notes: Step 3 >>>
-  Start this step by acknowledging the previous step.
-  Define terms and link to docs.github.com.
--->
-
-## Step 3: Add actions to your workflow file
+## Step 3: Add a step to your workflow file
 
 _Nice work adding a job to your workflow! :dancer:_
 
-Workflows have jobs, and jobs have steps. So now we'll add steps to your workflow.
+Workflows have jobs, and jobs have steps. So now we'll add a step to your workflow.
+
+**What are _steps_?**: Actions steps run - in the order they are specified, from the top down - when a workflow job is processed. Each step must pass for the next step to run.
 
-**What are _steps_?**: Actions steps will run during our job in order. Each step is either a shell script that will be executed, or an action that will be run. Each step must pass for the next step to run. Actions steps can be used from within the same repository, from any other public repository, or from a published Docker container image.
+Each step consists of either a shell script that's executed, or a reference to an action that's run. When we talk about an action (with a lowercase "a") in this context, we mean a reusable unit of code. You can find out about actions in "[Finding and customizing actions](https://docs.github.com/en/actions/learn-github-actions/finding-and-customizing-actions)," but for now we'll use a shell script in our workflow step.
 
-In our action, we post a comment on the pull request using a [bash](https://en.wikipedia.org/wiki/Bash_%28Unix_shell%29) script and [GitHub CLI](https://cli.github.com/).
+Update your workflow to make it post a comment on new pull requests. It will do this using a [bash](https://en.wikipedia.org/wiki/Bash_%28Unix_shell%29) script and [GitHub CLI](https://cli.github.com/).
 
-### :keyboard: Activity: Add Actions steps to your workflow file
+### :keyboard: Activity: Add a step to your workflow file
 
-1. Open your `welcome.yml` file.
-2. Update the contents of the file to:
-   ```yaml
+1. Still working on the `welcome-workflow` branch, open your `welcome.yml` file.
+1. Update the contents of the file to:
+
+   ```yaml copy
    name: Post welcome comment
    on:
      pull_request:
@@ -35,6 +32,9 @@ In our action, we post a comment on the pull request using a [bash](https://en.w
              GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
              PR_URL: ${{ github.event.pull_request.html_url }}
    ```
-3. Click **Commit changes...** in the top right of the workflow editor.
-4. Type your commit message and commit your changes directly to your branch.
-5. Wait about 20 seconds for actions to run, then refresh this page (the one you're following instructions from) and an action will automatically close this step and open the next one.
+
+   **Note:** The step you've added uses GitHub CLI (`gh`) to add a comment when a pull request is opened. To allow GitHub CLI to post a comment, we set the `GITHUB_TOKEN` environment variable to the value of the `GITHUB_TOKEN` secret, which is an installation access token, created when the workflow runs. For more information, see "[Automatic token authentication](https://docs.github.com/en/actions/security-guides/automatic-token-authentication)." We set the `PR_URL` environment variable to the URL of the newly created pull request, and we use this in the `gh` command.
+
+1. Click **Commit changes** in the top right of the workflow editor.
+1. Type your commit message and commit your changes directly to your branch.
+1. Wait about 20 seconds, then refresh this page (the one you're following instructions from). Another workflow will run and will replace this content with instructions for the next step.

.github/steps/4-merge-your-pull-request.md

@@ -1,9 +1,3 @@
-<!--
-  <<< Author notes: Step 4 >>>
-  Start this step by acknowledging the previous step.
-  Define terms and link to docs.github.com.
--->
-
 ## Step 4: Merge your workflow file
 
 _You're now able to write and run an Actions workflow! :sparkles:_
@@ -16,4 +10,4 @@ Merge your changes so the action will be a part of the `main` branch.
 1. Click on the pull request you created in step 1.
 1. Click **Merge pull request**, then click **Confirm merge**.
 1. Optionally, click **Delete branch** to delete your `welcome-workflow` branch.
-1. Wait about 20 seconds for actions to run, then refresh this page (the one you're following instructions from) and an action will automatically close this step and open the next one.
+1. Wait about 20 seconds, then refresh this page (the one you're following instructions from). Another workflow will run and will replace this content with instructions for the next step.

.github/steps/5-trigger.md

@@ -1,23 +1,18 @@
-<!--
-  <<< Author notes: Step 5 >>>
-  Start this step by acknowledging the previous step.
-  Define terms and link to docs.github.com.
--->
-
 ## Step 5: Trigger the workflow
 
-_You've now got a fully functioning workflow! :smile:_
+_You've now added a fully functioning workflow to your repository! :smile:_
 
-Your new action will run any time a pull request has been opened.
+The shell script in the workflow will run whenever a new pull request is opened.
 
-**Seeing your _action_ in action**: The status of your action is shown in a pull request before you merge, look for **All checks have passed** when you try out the steps below. You can also view them from the **Actions** tab in your repository. From there, you will see all the actions that have run, and you can click on each action to view details and access log files.
+**Seeing your _action_ in action**: The status of each workflow run that's triggered is shown in the pull request before it's merged: look for **All checks have passed** when you try out the steps below. You can also see a list of all the workflows that are running, or have finished running, in the **Actions** tab of your repository. From there, you can click on each workflow run to view more details and access log files.
 
-![View an action's log](https://user-images.githubusercontent.com/16547949/62388049-4e64e600-b52a-11e9-8bf5-db0c5452360f.png)
+![A screenshot of the Actions tab showing a list of workflow runs.](https://user-images.githubusercontent.com/16547949/62388049-4e64e600-b52a-11e9-8bf5-db0c5452360f.png)
 
 ### :keyboard: Activity: Trigger the workflow
 
 1. Make a new branch named `test-workflow`.
-1. Commit any change to your branch, such as adding an emoji to your README.md file.
-1. Create the pull request on your branch.
-1. See your action run on your pull request.
-1. Wait about 20 seconds for actions to run, then refresh this page (the one you're following instructions from) and an action will automatically close this step and open the next one.
+1. Make a change, such as adding an emoji to your README.md file, and commit the change directly to your new branch.
+1. In the **Pull requests** tab, create a pull request that will merge `test-workflow` into `main`.
+1. Watch the workflow running in the checks section of the pull request.
+1. Notice the comment that the workflow adds to the pull request.
+1. Wait about 20 seconds, then refresh this page (the one you're following instructions from). Another workflow will run and will replace this content with instructions for the next step.

.github/steps/X-finish.md

@@ -1,26 +1,21 @@
-<!--
-  <<< Author notes: Finish >>>
-  Review what we learned, ask for feedback, provide next steps.
--->
-
 ## Finish
 
 _Congratulations friend, you've completed this course!_
 
-<img src=https://octodex.github.com/images/jetpacktocat.png alt=celebrate width=300 align=right>
+<img src=https://octodex.github.com/images/jetpacktocat.png alt="Mona the Octocat wearing a jetpack and smiling." width=300 align=right>
 
 Here's a recap of all the tasks you've accomplished in your repository:
 
 - You've created your first GitHub Actions workflow file.
 - You learned where to make your workflow file.
-- You created an event trigger, a job, and steps for your workflow.
+- You defined an event trigger, a job, and a step for your workflow.
 - You're ready to automate anything you can dream of.
 
 ### What's next?
 
-- Learn more about GitHub Actions by reading "[Learn GitHub Actions](https://docs.github.com/actions/learn-github-actions)".
-- Use actions created by others in [awesome-actions](https://github.com/sdras/awesome-actions).
-- We'd love to hear what you thought of this course [in our discussion board](https://github.com/orgs/skills/discussions/categories/hello-github-actions).
-- [Take another GitHub Skills course](https://github.com/skills).
-- Learn more about GitHub by reading the "[Get started](https://docs.github.com/get-started)" docs.
-- To find projects to contribute to, check out [GitHub Explore](https://github.com/explore).
+- Learn more about GitHub Actions by reading "[Learn GitHub Actions](https://docs.github.com/actions/learn-github-actions)"
+- Use actions created by others in [awesome-actions](https://github.com/sdras/awesome-actions)
+- We'd love to hear what you thought of this course [in our discussion board](https://github.com/orgs/skills/discussions/categories/hello-github-actions)
+- [Take another course on GitHub Actions](https://skills.github.com/#automate-workflows-with-github-actions)
+- Learn more about GitHub by reading the "[Get started](https://docs.github.com/get-started)" docs
+- To find projects to contribute to, check out [GitHub Explore](https://github.com/explore)

README.md

@@ -1,24 +1,11 @@
 <header>
 
-<!--
-  <<< Author notes: Course header >>>
-  Include a 1280x640 image, course title in sentence case, and a concise description in emphasis.
-  In your repository settings: enable template repository, add your 1280x640 social image, auto delete head branches.
-  Add your open source license, GitHub uses MIT license.
--->
-
 # Hello GitHub Actions
 
-_Create a GitHub Action and use it in a workflow._
+_Create and run a GitHub Actions workflow._
 
 </header>
 
-<!--
-  <<< Author notes: Course start >>>
-  Include start button, a note about Actions minutes,
-  and tell the learner why they should take the course.
--->
-
 ## Welcome
 
 Automation is key for streamlining your work processes, and [GitHub Actions](https://docs.github.com/actions) is the best way to supercharge your workflow.
@@ -33,23 +20,12 @@ In this course, you will:
 
 1. Create a workflow
 2. Add a job
-3. Add actions
+3. Add a run step
 4. Merge your pull request
-5. See the action run
+5. See effect of the workflow
 
 ### How to start this course
 
-<!-- For start course, run in JavaScript:
-'https://github.com/new?' + new URLSearchParams({
-  template_owner: 'skills',
-  template_name: 'hello-github-actions',
-  owner: '@me',
-  name: 'skills-hello-github-actions',
-  description: 'My clone repository',
-  visibility: 'public',
-}).toString()
--->
-
 [![start-course](https://user-images.githubusercontent.com/1221423/235727646-4a590299-ffe5-480d-8cd5-8194ea184546.svg)](https://github.com/new?template_owner=skills&template_name=hello-github-actions&owner=%40me&name=skills-hello-github-actions&description=My+clone+repository&visibility=public)
 
 1. Right-click **Start course** and open the link in a new tab.
@@ -61,11 +37,6 @@ In this course, you will:
 
 <footer>
 
-<!--
-  <<< Author notes: Footer >>>
-  Add a link to get support, GitHub status page, code of conduct, license link.
--->
-
 ---
 
 Get help: [Post in our discussion board](https://github.com/orgs/skills/discussions/categories/hello-github-actions) &bull; [Review the GitHub status page](https://www.githubstatus.com/)