From 59b848dfae22b87d4ae04a409ce4535c2d488e04 Mon Sep 17 00:00:00 2001 From: Kevin Heis Date: Tue, 30 May 2023 10:02:54 -0700 Subject: [PATCH 1/8] Update course format for accessibility --- .github/script/update-step.sh | 12 ++++----- .github/{script/STEP => steps/-step.txt} | 0 .github/steps/0-welcome.md | 1 + .../workflows/{0-start.yml => 0-welcome.yml} | 26 +++++++++---------- .../1-initialize-javascript-project.yml | 20 +++++++------- .github/workflows/2-configure-your-action.yml | 20 +++++++------- .github/workflows/3-create-metadata-file.yml | 20 +++++++------- .../4-create-javascript-files-for-action.yml | 20 +++++++------- .../5-add-action-to-workflow-file.yml | 20 +++++++------- .github/workflows/6-trigger-action.yml | 20 +++++++------- README.md | 19 ++++++++------ 11 files changed, 84 insertions(+), 94 deletions(-) rename .github/{script/STEP => steps/-step.txt} (100%) create mode 100644 .github/steps/0-welcome.md rename .github/workflows/{0-start.yml => 0-welcome.yml} (78%) diff --git a/.github/script/update-step.sh b/.github/script/update-step.sh index db99b88..70d79a2 100755 --- a/.github/script/update-step.sh +++ b/.github/script/update-step.sh @@ -3,7 +3,7 @@ # chmod a+x .github/script/update-step.sh echo "Check that we are on FROM_STEP" -if [ "$(cat .github/script/STEP)" != $FROM_STEP ] +if [ "$(cat .github/steps/-step.txt)" != $FROM_STEP ] then echo "Current step is not $FROM_STEP" exit 0 @@ -17,18 +17,18 @@ sed -r 's/
/
/g' README.md > tmp mv tmp README.md echo "Add 'open' to step TO_STEP" -sed -r "s/
/
/g" README.md > tmp +sed -r "s/
/
/g" README.md > tmp mv tmp README.md -echo "Update the STEP file to TO_STEP" -echo "$TO_STEP" > .github/script/STEP +echo "Update the step file to TO_STEP" +echo "$TO_STEP" > .github/steps/-step.txt echo "Commit the files, and push to main" git config user.name github-actions git config user.email github-actions@github.com git add README.md -git add .github/script/STEP -git commit --message="Update to $TO_STEP in STEP and README.md" +git add .github/steps/-step.txt +git commit --message="Update to $TO_STEPin step and README.md" git push echo "If BRANCH_NAME, update that branch as well" diff --git a/.github/script/STEP b/.github/steps/-step.txt similarity index 100% rename from .github/script/STEP rename to .github/steps/-step.txt diff --git a/.github/steps/0-welcome.md b/.github/steps/0-welcome.md new file mode 100644 index 0000000..9ff13a5 --- /dev/null +++ b/.github/steps/0-welcome.md @@ -0,0 +1 @@ + diff --git a/.github/workflows/0-start.yml b/.github/workflows/0-welcome.yml similarity index 78% rename from .github/workflows/0-start.yml rename to .github/workflows/0-welcome.yml index 9458afe..a093f15 100644 --- a/.github/workflows/0-start.yml +++ b/.github/workflows/0-welcome.yml @@ -1,14 +1,13 @@ -name: Step 0, Start +name: Step 0, Welcome # This step triggers after the learner creates a new repository from the template -# This step sets STEP to 1 -# This step closes
and opens
+# This workflow updates from step 0 to step 1. # When creating a repository from a template, there is variability in the # order and timing of events that fire and when workflow triggers are registered. # Given that, these triggers are purposely broad to ensure this workflow is always triggered. # The conditions within the on_start job are to ensure it is only fully executed once. -# Reference https://docs.github.com/en/actions/learn-github-actions/events-that-trigger-workflows +# Reference: https://docs.github.com/en/actions/learn-github-actions/events-that-trigger-workflows on: create: workflow_dispatch: @@ -19,7 +18,7 @@ permissions: issues: write jobs: - # Get the current step from .github/script/STEP so we can + # Get the current step from .github/steps/-step.txt so we can # limit running the main job when the learner is on the same step. get_current_step: name: Check current step number @@ -29,7 +28,7 @@ jobs: uses: actions/checkout@v3 - id: get_step run: | - echo "current_step=$(cat ./.github/script/STEP)" >> $GITHUB_OUTPUT + echo "current_step=$(cat ./.github/steps/-step.txt)" >> $GITHUB_OUTPUT outputs: current_step: ${{ steps.get_step.outputs.current_step }} @@ -39,9 +38,9 @@ jobs: # We will only run this action when: # 1. This repository isn't the template repository - # 2. The STEP is currently 0 - # Reference https://docs.github.com/en/actions/learn-github-actions/contexts - # Reference https://docs.github.com/en/actions/learn-github-actions/expressions + # 2. The step is currently 0 + # Reference: https://docs.github.com/en/actions/learn-github-actions/contexts + # Reference: https://docs.github.com/en/actions/learn-github-actions/expressions if: >- ${{ !github.event.repository.is_template && needs.get_current_step.outputs.current_step == 0 }} @@ -62,7 +61,7 @@ jobs: - name: Prepare labels run: | echo "Make sure we are on step 0" - if [ "$(cat .github/script/STEP)" != 0 ] + if [ "$(cat .github/steps/-step.txt)" != 0 ] then echo "Current step is not 0" exit 0 @@ -79,7 +78,7 @@ jobs: - name: Prepare issues run: | echo "Make sure we are on step 0" - if [ "$(cat .github/script/STEP)" != 0 ] + if [ "$(cat .github/steps/-step.txt)" != 0 ] then echo "Current step is not 0" exit 0 @@ -91,9 +90,8 @@ jobs: # Update README to close
# and open
- # and set STEP to '1' - - name: Update to step 1 - uses: skills/action-update-step@v1 + - name: Update to step 1 + uses: skills/action-update-step@v2 with: token: ${{ secrets.GITHUB_TOKEN }} from_step: 0 diff --git a/.github/workflows/1-initialize-javascript-project.yml b/.github/workflows/1-initialize-javascript-project.yml index a7a76ba..42c5332 100644 --- a/.github/workflows/1-initialize-javascript-project.yml +++ b/.github/workflows/1-initialize-javascript-project.yml @@ -1,11 +1,10 @@ name: Step 1, Initialize JavaScript Project # This step listens for the learner pushing a commit to `main` -# This step sets STEP to 2 -# This step closes
and opens
+# This workflow updates from step 1 to step 2. # This will run every time we push a commit to `main` -# Reference https://docs.github.com/en/actions/learn-github-actions/events-that-trigger-workflows +# Reference: https://docs.github.com/en/actions/learn-github-actions/events-that-trigger-workflows on: workflow_dispatch: @@ -19,7 +18,7 @@ permissions: contents: write jobs: - # Get the current step from .github/script/STEP so we can + # Get the current step from .github/steps/-step.txt so we can # limit running the main job when the learner is on the same step. get_current_step: name: Check current step number @@ -29,7 +28,7 @@ jobs: uses: actions/checkout@v3 - id: get_step run: | - echo "current_step=$(cat ./.github/script/STEP)" >> $GITHUB_OUTPUT + echo "current_step=$(cat ./.github/steps/-step.txt)" >> $GITHUB_OUTPUT outputs: current_step: ${{ steps.get_step.outputs.current_step }} @@ -39,9 +38,9 @@ jobs: # We will only run this action when: # 1. This repository isn't the template repository - # 2. The STEP is currently 1 - # Reference https://docs.github.com/en/actions/learn-github-actions/contexts - # Reference https://docs.github.com/en/actions/learn-github-actions/expressions + # 2. The step is currently 1 + # Reference: https://docs.github.com/en/actions/learn-github-actions/contexts + # Reference: https://docs.github.com/en/actions/learn-github-actions/expressions if: >- ${{ !github.event.repository.is_template && needs.get_current_step.outputs.current_step == 1 }} @@ -68,10 +67,9 @@ jobs: # Update README to close
# and open
- # and set STEP to '2' - - name: Update to step 2 + - name: Update to step 2 if: steps.check_files.outputs.files_exists == 'true' - uses: skills/action-update-step@v1 + uses: skills/action-update-step@v2 with: token: ${{ secrets.GITHUB_TOKEN }} from_step: 1 diff --git a/.github/workflows/2-configure-your-action.yml b/.github/workflows/2-configure-your-action.yml index 97c6c7b..34ac00a 100644 --- a/.github/workflows/2-configure-your-action.yml +++ b/.github/workflows/2-configure-your-action.yml @@ -1,11 +1,10 @@ name: Step 2, Configure Your Action # This step listens for the learner pushing a commit to `main` -# This step sets STEP to 3 -# This step closes
and opens
+# This workflow updates from step 2 to step 3. # This will run every time we push a commit to `main` -# Reference https://docs.github.com/en/actions/learn-github-actions/events-that-trigger-workflows +# Reference: https://docs.github.com/en/actions/learn-github-actions/events-that-trigger-workflows on: workflow_dispatch: push: @@ -18,7 +17,7 @@ permissions: contents: write jobs: - # Get the current step from .github/script/STEP so we can + # Get the current step from .github/steps/-step.txt so we can # limit running the main job when the learner is on the same step. get_current_step: name: Check current step number @@ -28,7 +27,7 @@ jobs: uses: actions/checkout@v3 - id: get_step run: | - echo "current_step=$(cat ./.github/script/STEP)" >> $GITHUB_OUTPUT + echo "current_step=$(cat ./.github/steps/-step.txt)" >> $GITHUB_OUTPUT outputs: current_step: ${{ steps.get_step.outputs.current_step }} @@ -38,9 +37,9 @@ jobs: # We will only run this action when: # 1. This repository isn't the template repository - # 2. The STEP is currently 2 - # Reference https://docs.github.com/en/actions/learn-github-actions/contexts - # Reference https://docs.github.com/en/actions/learn-github-actions/expressions + # 2. The step is currently 2 + # Reference: https://docs.github.com/en/actions/learn-github-actions/contexts + # Reference: https://docs.github.com/en/actions/learn-github-actions/expressions if: >- ${{ !github.event.repository.is_template && needs.get_current_step.outputs.current_step == 2 }} @@ -68,10 +67,9 @@ jobs: # Update README to close
# and open
- # and set STEP to '3' - - name: Update to step 3 + - name: Update to step 3 if: steps.check_files.outputs.files_exists == 'true' - uses: skills/action-update-step@v1 + uses: skills/action-update-step@v2 with: token: ${{ secrets.GITHUB_TOKEN }} from_step: 2 diff --git a/.github/workflows/3-create-metadata-file.yml b/.github/workflows/3-create-metadata-file.yml index 267acc8..82a873f 100644 --- a/.github/workflows/3-create-metadata-file.yml +++ b/.github/workflows/3-create-metadata-file.yml @@ -1,11 +1,10 @@ name: Step 3, Create Metadata File # This step listens for the learner pushing a commit to `main` -# This step sets STEP to 4 -# This step closes
and opens
+# This workflow updates from step 3 to step 4. # This will run every time we push a commit to `main` -# Reference https://docs.github.com/en/actions/learn-github-actions/events-that-trigger-workflows +# Reference: https://docs.github.com/en/actions/learn-github-actions/events-that-trigger-workflows on: workflow_dispatch: push: @@ -20,7 +19,7 @@ env: EXPECTED_METADATA: outputs jobs: - # Get the current step from .github/script/STEP so we can + # Get the current step from .github/steps/-step.txt so we can # limit running the main job when the learner is on the same step. get_current_step: name: Check current step number @@ -30,7 +29,7 @@ jobs: uses: actions/checkout@v3 - id: get_step run: | - echo "current_step=$(cat ./.github/script/STEP)" >> $GITHUB_OUTPUT + echo "current_step=$(cat ./.github/steps/-step.txt)" >> $GITHUB_OUTPUT outputs: current_step: ${{ steps.get_step.outputs.current_step }} @@ -40,9 +39,9 @@ jobs: # We will only run this action when: # 1. This repository isn't the template repository - # 2. The STEP is currently 3 - # Reference https://docs.github.com/en/actions/learn-github-actions/contexts - # Reference https://docs.github.com/en/actions/learn-github-actions/expressions + # 2. The step is currently 3 + # Reference: https://docs.github.com/en/actions/learn-github-actions/contexts + # Reference: https://docs.github.com/en/actions/learn-github-actions/expressions if: >- ${{ !github.event.repository.is_template && needs.get_current_step.outputs.current_step == 3 }} @@ -70,10 +69,9 @@ jobs: # Update README to close
# and open
- # and set STEP to '4' - - name: Update to step 4 + - name: Update to step 4 if: (contains(steps.read_action_yml_file.outputs.contents, ${{ env.EXPECTED_METADATA }}) - uses: skills/action-update-step@v1 + uses: skills/action-update-step@v2 with: token: ${{ secrets.GITHUB_TOKEN }} from_step: 3 diff --git a/.github/workflows/4-create-javascript-files-for-action.yml b/.github/workflows/4-create-javascript-files-for-action.yml index 4b3e343..05b800c 100644 --- a/.github/workflows/4-create-javascript-files-for-action.yml +++ b/.github/workflows/4-create-javascript-files-for-action.yml @@ -1,11 +1,10 @@ name: Step 4, Create JavaScript Files For Action # This step listens for the learner pushing a commit to `main` -# This step sets STEP to 5 -# This step closes
and opens
+# This workflow updates from step 4 to step 5. # This will run every time we push a commit to `main` -# Reference https://docs.github.com/en/actions/learn-github-actions/events-that-trigger-workflows +# Reference: https://docs.github.com/en/actions/learn-github-actions/events-that-trigger-workflows on: workflow_dispatch: push: @@ -17,7 +16,7 @@ permissions: contents: write jobs: - # Get the current step from .github/script/STEP so we can + # Get the current step from .github/steps/-step.txt so we can # limit running the main job when the learner is on the same step. get_current_step: name: Check current step number @@ -27,7 +26,7 @@ jobs: uses: actions/checkout@v3 - id: get_step run: | - echo "current_step=$(cat ./.github/script/STEP)" >> $GITHUB_OUTPUT + echo "current_step=$(cat ./.github/steps/-step.txt)" >> $GITHUB_OUTPUT outputs: current_step: ${{ steps.get_step.outputs.current_step }} @@ -37,9 +36,9 @@ jobs: # We will only run this action when: # 1. This repository isn't the template repository - # 2. The STEP is currently 4 - # Reference https://docs.github.com/en/actions/learn-github-actions/contexts - # Reference https://docs.github.com/en/actions/learn-github-actions/expressions + # 2. The step is currently 4 + # Reference: https://docs.github.com/en/actions/learn-github-actions/contexts + # Reference: https://docs.github.com/en/actions/learn-github-actions/expressions if: >- ${{ !github.event.repository.is_template && needs.get_current_step.outputs.current_step == 4 }} @@ -67,10 +66,9 @@ jobs: # Update README to close
# and open
- # and set STEP to '5' - - name: Update to step 5 + - name: Update to step 5 if: steps.check_files.outputs.files_exists == 'true' - uses: skills/action-update-step@v1 + uses: skills/action-update-step@v2 with: token: ${{ secrets.GITHUB_TOKEN }} from_step: 4 diff --git a/.github/workflows/5-add-action-to-workflow-file.yml b/.github/workflows/5-add-action-to-workflow-file.yml index 92878ed..93412b5 100644 --- a/.github/workflows/5-add-action-to-workflow-file.yml +++ b/.github/workflows/5-add-action-to-workflow-file.yml @@ -1,11 +1,10 @@ name: Step 5, Add Action To Workflow File # This step listens for the learner pushing a commit to `main` -# This step sets STEP to 6 -# This step closes
and opens
+# This workflow updates from step 5 to step 6. # This will run every time we push a commit to `main` -# Reference https://docs.github.com/en/actions/learn-github-actions/events-that-trigger-workflows +# Reference: https://docs.github.com/en/actions/learn-github-actions/events-that-trigger-workflows on: workflow_dispatch: push: @@ -20,7 +19,7 @@ env: EXPECTED_METADATA: ha-ha jobs: - # Get the current step from .github/script/STEP so we can + # Get the current step from .github/steps/-step.txt so we can # limit running the main job when the learner is on the same step. get_current_step: name: Check current step number @@ -30,7 +29,7 @@ jobs: uses: actions/checkout@v3 - id: get_step run: | - echo "current_step=$(cat ./.github/script/STEP)" >> $GITHUB_OUTPUT + echo "current_step=$(cat ./.github/steps/-step.txt)" >> $GITHUB_OUTPUT outputs: current_step: ${{ steps.get_step.outputs.current_step }} @@ -40,9 +39,9 @@ jobs: # We will only run this action when: # 1. This repository isn't the template repository - # 2. The STEP is currently 5 - # Reference https://docs.github.com/en/actions/learn-github-actions/contexts - # Reference https://docs.github.com/en/actions/learn-github-actions/expressions + # 2. The step is currently 5 + # Reference: https://docs.github.com/en/actions/learn-github-actions/contexts + # Reference: https://docs.github.com/en/actions/learn-github-actions/expressions if: >- ${{ !github.event.repository.is_template && needs.get_current_step.outputs.current_step == 5 }} @@ -70,10 +69,9 @@ jobs: # Update README to close
# and open
- # and set STEP to '6' - - name: Update to step 6 + - name: Update to step 6 if: (contains(steps.read_action_yml_file.outputs.contents, ${{ env.EXPECTED_METADATA }}) - uses: skills/action-update-step@v1 + uses: skills/action-update-step@v2 with: token: ${{ secrets.GITHUB_TOKEN }} from_step: 5 diff --git a/.github/workflows/6-trigger-action.yml b/.github/workflows/6-trigger-action.yml index e33a50b..b0c6962 100644 --- a/.github/workflows/6-trigger-action.yml +++ b/.github/workflows/6-trigger-action.yml @@ -1,11 +1,10 @@ name: Step 6, Trigger Your Action # This step listens for the learner applying a label to an issue -# This step sets STEP to X -# This step closes
and opens
+# This workflow updates from step to step X. # This will run every time we apply a label to an issue -# Reference https://docs.github.com/en/actions/learn-github-actions/events-that-trigger-workflows +# Reference: https://docs.github.com/en/actions/learn-github-actions/events-that-trigger-workflows on: workflow_dispatch: issues: @@ -20,7 +19,7 @@ env: EXPECTED_METADATA: "second joke" jobs: - # Get the current step from .github/script/STEP so we can + # Get the current step from .github/steps/-step.txt so we can # limit running the main job when the learner is on the same step. get_current_step: name: Check current step number @@ -30,7 +29,7 @@ jobs: uses: actions/checkout@v3 - id: get_step run: | - echo "current_step=$(cat ./.github/script/STEP)" >> $GITHUB_OUTPUT + echo "current_step=$(cat ./.github/steps/-step.txt)" >> $GITHUB_OUTPUT outputs: current_step: ${{ steps.get_step.outputs.current_step }} @@ -40,9 +39,9 @@ jobs: # We will only run this action when: # 1. This repository isn't the template repository - # 2. The STEP is currently 6 - # Reference https://docs.github.com/en/actions/learn-github-actions/contexts - # Reference https://docs.github.com/en/actions/learn-github-actions/expressions + # 2. The step is currently 6 + # Reference: https://docs.github.com/en/actions/learn-github-actions/contexts + # Reference: https://docs.github.com/en/actions/learn-github-actions/expressions if: >- ${{ !github.event.repository.is_template && needs.get_current_step.outputs.current_step == 6 }} @@ -63,10 +62,9 @@ jobs: # Update README to close
# and open
- # and set STEP to 'X' - - name: Update to step X + - name: Update to step X if: contains(github.event, ${{ env.EXPECTED_METADATA }}) - uses: skills/action-update-step@v1 + uses: skills/action-update-step@v2 with: token: ${{ secrets.GITHUB_TOKEN }} from_step: 6 diff --git a/README.md b/README.md index b1309ca..6b78db6 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ Include a 1280×640 image, course name in sentence case, and a concise description in emphasis. In your repository settings: enable template repository, add your 1280×640 social image, auto delete head branches. Next to "About", add description & tags; disable releases, packages, & environments. - Add your open source license, GitHub uses Creative Commons Attribution 4.0 International. + Add your open source license, GitHub uses MIT license. --> # Write JavaScript Actions @@ -11,12 +11,9 @@ _Write your own GitHub JavaScript Action and automate customized tasks unique to your workflow._
@@ -27,9 +24,15 @@ Write your own GitHub JavaScript Action and automate customized tasks unique to - **Who is this for**: Developers, GitHub users, users new to Git, students, managers, and for teams. - **What you'll learn**: How to consume actions within a workflow file, create custom JavaScript based actions and publish your newly created action to the marketplace. - **Prerequisites**: Before you start, you should be familiar with GitHub, GitHub Actions, and Continuous Integration with GitHub Actions. -- **How long**: This course is 6 steps long and takes about 1 to 2 hours to be completed. +- **How long**: This course takes about 1 to 2 hours to be completed. -## How to start this course +In this course, you will: + +1. +2. +3. + +### How to start this course -
-

Welcome

 +## Welcome Write your own GitHub JavaScript Action and automate customized tasks unique to your workflow. - **Who is this for**: Developers, GitHub users, users new to Git, students, managers, and for teams. - **What you'll learn**: How to consume actions within a workflow file, create custom JavaScript based actions and publish your newly created action to the marketplace. - **Prerequisites**: Before you start, you should be familiar with GitHub, GitHub Actions, and Continuous Integration with GitHub Actions. -- **How long**: This course takes about 1 to 2 hours to be completed. +- **How long**: This course takes about 1 to 2 hours to be completed. In this course, you will: @@ -54,7 +53,7 @@ In this course, you will: - Scroll down and click the **Create repository** button at the bottom of the form. 3. After your new repository is created, wait about 20 seconds, then refresh the page. Follow the step-by-step instructions in the new repository's README. -
+ + +
+ +

Step 1: Initialize a new JavaScript project

 + +_Welcome to the course :tada:_ + +### Configuring a workflow + +Actions are enabled on your repository by default, but we still have to tell our repository to use them. We do this by creating a workflow file in our repository. + +A **workflow** file can be thought of as the recipe for automating a task. They house the start to finish instructions, in the form of `jobs` and `steps`, for what should happen based on specific triggers. + +Your repository can contain multiple **workflow** files that carry out a wide variety of tasks. It is important to consider this when deciding on a name for your **workflow**. The name you choose should reflect the tasks being performed. + +_In our case, we will use this one **workflow** file for many things, which leads us to break this convention for teaching purposes._ + +Read more about [workflows](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/configuring-a-workflow#choosing-the-type-of-actions-for-your-workflow) + +## On to your development environment + +Our JavaScript actions are going to leverage the [GitHub ToolKit](https://github.com/actions/toolkit) for developing GitHub Actions. + +This is an external library that we will install using `npm` which means that you will need [Node.js](https://nodejs.org/) installed. + +We find writing actions to be easier from a local environment vs trying to do everything right here in the repository. Doing these steps locally allows you to use the editor of your choice so that you have all the extensions and snippets you are used to when writing code. + +If you do not have a preferred environment then we suggest following along exactly as you see on the screen, which means you'll need to install [Visual Studio Code](https://code.visualstudio.com/). + +## Don't forget to set up your workstation + +Most of your work going forward will take place away from your Skills repository, so before continuing with the course ensure you have the following installed on your **local machine**. + +1. [ ] [Node.js](https://nodejs.org) +2. [ ] [Visual Studio Code](https://code.visualstudio.com/) or your editor of choice +3. [ ] [Git](https://git-scm.com/) + +### :keyboard: Activity 1: Initialize a new JavaScript project + +Once you have the necessary tools installed locally, follow these steps to begin creating your first action. + +1. Open the **Terminal** (Mac and Linux) or **Command Prompt** (Windows) on your local machine +2. Clone your Skills repo to your local machine: + ```shell + git clone .git + ``` +3. Navigate to the folder you just cloned: + ```shell + cd + ``` +4. We are using branch called `main`. + ```shell + git switch main + ``` +5. Create a new folder for our actions files: + ```shell + mkdir -p .github/actions/joke-action + ``` +6. Navigate to the `joke-action` folder you just created: + ```shell + cd .github/actions/joke-action + ``` +7. Initialize a new project: + ```shell + npm init -y + ``` +8. Install the **request**, **request-promise** and **@actions/core** dependencies using `npm` from the [GitHub ToolKit] (https://github.com/actions/toolkit): + ```shell + npm install --save request request-promise @actions/core + ``` +9. Commit those newly added files,we will remove the need to upload **node_modules** in a later step: + ```shell + git add . + git commit -m 'add project dependencies' + ``` +10. Push your changes to your repository: + ```shell + git push + ``` +11. Wait about 20 seconds then refresh this page (the one you're following instructions from). [GitHub Actions](https://docs.github.com/en/actions) will automatically update to the next step. diff --git a/.github/steps/2-configure-your-action.md b/.github/steps/2-configure-your-action.md index e69de29..61f5798 100644 --- a/.github/steps/2-configure-your-action.md +++ b/.github/steps/2-configure-your-action.md @@ -0,0 +1,36 @@ + +## Step 2: Configure Your Action + +_Let's keep going! :bike:_ + +### Excellent! + +Now that we have the custom action pre-requisites, let us create **joke-action** action. + +### :keyboard: Activity 1: Configure Your Action + +All of the following steps take place inside of the `.github/actions/joke-action` directory. + +We will start with using the parameters that are **required** and later implement some optional parameters as our action evolves. + +1. Create a new file in: `.github/actions/joke-action/action.yml` +2. Add the following contents to the `.github/actions/joke-action/action.yml` file: + ```yaml + name: "my joke action" + + description: "use an external API to retrieve and display a joke" + + runs: + using: "node16" + main: "main.js" + ``` +3. Save the `action.yml` file +4. Commit the changes and push them to the `main` branch: + ```shell + git add action.yml + git commit -m 'create action.yml' + git pull + git push + ``` +5. Wait about 20 seconds then refresh this page (the one you're following instructions from). [GitHub Actions](https://docs.github.com/en/actions) will automatically update to the next step. + diff --git a/.github/steps/3-create-metadata-file.md b/.github/steps/3-create-metadata-file.md index e69de29..50fb9b6 100644 --- a/.github/steps/3-create-metadata-file.md +++ b/.github/steps/3-create-metadata-file.md @@ -0,0 +1,58 @@ + + +## Step 3: Create the metadata file + +_Nice work configuring your action :smile:_ + +## Action metadata + +Every GitHub Action that we write needs to be accompanied by a metadata file. This file has a few rules to it, as are indicated below: + +- Filename **must** be `action.yml`. +- Required for both Docker container and JavaScript actions. +- Written in YAML syntax. + +This file defines the following information about your action: + +| Parameter | Description | Required | +| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | :----------------: | +| Name | The name of your action. Helps visually identify the actions in a job. | :white_check_mark: | +| Description | A summary of what your action does. | :white_check_mark: | +| Inputs | Input parameters allow you to specify data that the action expects to use during runtime. These parameters become environment variables in the runner. | :x: | +| Outputs | Specifies the data that subsequent actions can use later in the workflow after the action that defines these outputs has run. | :x: | +| Runs | The command to run when the action executes. | :white_check_mark: | +| Branding | You can use a color and Feather icon to create a badge to personalize and distinguish your action in GitHub Marketplace. | :x: | + +--- + +Read more about [Action metadata](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/metadata-syntax-for-github-actions) + +### :keyboard: Activity 1: Create the metadata file + +All of the following steps take place inside of the `.github/actions/joke-action` directory. + +Our action does not require much metadata for it to run correctly. We will not be accepting any inputs, we will however be setting a single output this time. + +1. Update the action metadata file `.github/actions/joke-action/action.yml` with the following content: + ```yaml + name: "my joke action" + + description: "use an external API to retrieve and display a joke" + + outputs: + joke-output: + description: The resulting joke from the icanhazdadjokes API + + runs: + using: "node16" + main: "main.js" + ``` +2. Save the `action.yml` file +3. Commit the changes and push them to GitHub: + ```shell + git add action.yml + git commit -m 'add metadata for the joke action' + git pull + git push + ``` +4. Wait about 20 seconds then refresh this page (the one you're following instructions from). [GitHub Actions](https://docs.github.com/en/actions) will automatically update to the next step. diff --git a/.github/steps/4-create-javascript-files-for-action.md b/.github/steps/4-create-javascript-files-for-action.md index e69de29..3e4830e 100644 --- a/.github/steps/4-create-javascript-files-for-action.md +++ b/.github/steps/4-create-javascript-files-for-action.md @@ -0,0 +1,165 @@ + + + +## Step 4: Create the JavaScript files for your action + +_Good job adding the metadata file! :dancer:_ + +## Files + +As you probably know, in JavaScript and other programming languages it is common to break your code into modules so that it is easier to read and maintain going forward. Since JavaScript actions are just programs written in JavaScript that run based on a specific trigger we are able to make our action code modular as well. + +To do so we will create two files. One of them will contain the logic to reach out to an external API and retrieve a joke for us, the other will call that module and print the joke to the actions console for us. We will be extending this functionality in our third and final action. + +### Fetching a joke + +**Joke API** + + +The first file will be `joke.js` and it will fetch our joke for us. We will be using the [icanhazdadjoke API](https://icanhazdadjoke.com/api) for our action. This API does not require any authentication, but it does however that we set a few parameters in the [HTTP headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers). We need to point out what those are when we get to the code, however it is outside of the scope of this course to cover HTTP in any depth. + +When we make our request to this API we will get back a JSON Object in the response. That Object looks like this: + +``` +{ + id: '0LuXvkq4Muc', + joke: "I knew I shouldn't steal a mixer from work, but it was a whisk I was willing to take.", + status: 200 +} +``` + +It contains 3 key/value pairs of data that we can use in our own program or service. In our case, we are only interested in the `joke` field. + +**Joke Module** + +We will create a file named `joke.js` and it will reside in the `.github/action/joke-action` directory. + +The joke module will look like this: + +```javascript +const request = require("request-promise"); + +const options = { + method: "GET", + uri: "https://icanhazdadjoke.com/", + headers: { + Accept: "application/json", + "User-Agent": + "Writing JavaScript action GitHub Skills course." + }, + json: true +}; + +async function getJoke() { + const res = await request(options); + return res.joke; +} + +module.exports = getJoke; +``` + +
Need an advanced description of the joke.js source code? +We first bring in the `request-promise` library that we installed earlier using `npm`. + +Next we define a set of `options` that the `request-promise` library will use when it makes the request. + +Read more about [request-promise](https://github.com/request/request-promise/) + +Inside of the `options` block we add a key named `headers`. This defines the HTTP headers that the **icanhazdadjoke** API expects in each request that comes it's way. + +**icanhazdadjoke** cares the most about the keys, **Accept** and **User-Agent**, so we need to make sure we fill them in. + +Next we define an **asynchronous JavaScript function** to make the request for us, storing the JSON Object that is returned in a variable named `res`. + +Lastly, we `return` the `res.joke` which is only the value associated with the `joke` key of the JSON Object. This value will be random every time our action runs because of how we are interacting with the **icanhazdadjoke** API. + +This file finishes up by exporting the newly created function so that we can use it in our `main.js` file. + + + +### Creating the main entry point for your action + +**Main Module** + +We will also create a file named `main.js` that resides inside of the `.github/actions/joke-action` directory. + +That file will look like this: + +```javascript +const getJoke = require("./joke"); +const core = require("@actions/core"); + +async function run() { + const joke = await getJoke(); + console.log(joke); + core.setOutput("joke-output", joke); +} + +run(); +``` + +
Need an advanced description of the main.js source code? +Like we did in the `joke.js` file, we are first going to bring in our dependencies. Only this time, our dependencies include something we wrote! To do that we simply use `require()` to point to the location of the file we wish to bring in. + +We also bring in `@actions/core` so that we can set the output of our action. + +Next we write another **asynchronous JavaScript function** that stores the return value of `getJoke()` in a variable called **joke**. + +Then we log the joke to the console. + +Finally we finish the function with by setting the contents of the joke as the value of the `joke-output` output parameter. We will use this output later in the course. +_Don't forget to call the `run()` function._ + + + +### :keyboard: Activity 1: Creating the JavaScript files for your new action. + +1. Create and add the following contents to the `.github/actions/joke-action/joke.js` file: + + ```javascript + const request = require("request-promise"); + + const options = { + method: "GET", + uri: "https://icanhazdadjoke.com/", + headers: { + Accept: "application/json", + "User-Agent": + "Writing JavaScript action GitHub Skills course." + }, + json: true + }; + + async function getJoke() { + const res = await request(options); + return res.joke; + } + + module.exports = getJoke; + ``` + +2. Save the `joke.js` file. +3. Create and add the following contents to the `.github/actions/joke-action/main.js` file: + + ```javascript + const getJoke = require("./joke"); + const core = require("@actions/core"); + + async function run() { + const joke = await getJoke(); + console.log(joke); + core.setOutput("joke-output", joke); + } + + run(); + ``` + +4. Save the `main.js` file. +5. Commit the changes to this branch and push them to GitHub: + ```shell + git add joke.js main.js + git commit -m 'creating joke.js and main.js' + git pull + git push + ``` +6. Wait about 20 seconds then refresh this page (the one you're following instructions from). [GitHub Actions](https://docs.github.com/en/actions) will automatically update to the next step. diff --git a/.github/steps/5-add-action-to-workflow-file.md b/.github/steps/5-add-action-to-workflow-file.md index e69de29..07f051e 100644 --- a/.github/steps/5-add-action-to-workflow-file.md +++ b/.github/steps/5-add-action-to-workflow-file.md @@ -0,0 +1,40 @@ + + + +## Step 5: Add your action to the workflow file + +_Great job! :tada:_ + +All of the following steps will add the action to the workflow file that’s already in the repo [`my-workflow.yml` file](/.github/workflows/my-workflow.yml) + +### :keyboard: Activity 1: Edit the custom action at the bottom of the workflow file. + +```yaml + - name: ha-ha + uses: ./.github/actions/joke-action +``` + +Here is what the full file should look like (we’re using issues instead of the pull request event and removing the reference to the hello world action.) + +```yaml +name: JS Actions + +on: + issues: + types: [labeled] + +jobs: + action: + if: ${{ !github.event.repository.is_template }} + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v3 + - name: ha-ha + uses: ./.github/actions/joke-action + +``` + +You can make these changes in your repository by opening [`my-workflow.yml`](/.github/workflows/my-workflow.yml) in another browser tab and [editing the file directly](https://docs.github.com/en/repositories/working-with-files/managing-files/editing-files). Make sure to select the `Commit directly to the main branch` option. + +Wait about 20 seconds then refresh this page (the one you're following instructions from). [GitHub Actions](https://docs.github.com/en/actions) will automatically update to the next step. diff --git a/.github/steps/6-trigger-action.md b/.github/steps/6-trigger-action.md index e69de29..15176da 100644 --- a/.github/steps/6-trigger-action.md +++ b/.github/steps/6-trigger-action.md @@ -0,0 +1,13 @@ +## Step 6: Trigger the joke action + +_Great job! :heart:_ + +Everything is all set up and now we are ready to start laughing. You will find you have some joke related labels available to you in this repository. You don't have to use them, any label will trigger our workflow, but the easiest way to follow along would be to use suggested labels. + +### Trigger a joke + +1. Open issue #1 in the "Issues tab" +2. Apply the `first-joke` label to the issue +3. Wait a few seconds and then apply the `second-joke` label to the issue +4. Check the `JS Actions` workflow results on the "Actions tab" +5. Wait about 20 seconds then refresh this page (the one you're following instructions from). [GitHub Actions](https://docs.github.com/en/actions) will automatically update to the next step. diff --git a/.github/steps/X-finish.md b/.github/steps/X-finish.md index e69de29..d64eded 100644 --- a/.github/steps/X-finish.md +++ b/.github/steps/X-finish.md @@ -0,0 +1,29 @@ + +## Finish + +celebrate + +### Congratulations, you've completed this course! + +In this course, you've learned a lot about developing custom actions using JavaScript and Actions Toolkit. + +## Publishing your actions + +Publishing your actions is a great way to help others in your team and across the GitHub community. Although actions do not need to be published to be consumed, by adding them to the marketplace you make them easier to find. + +Some notable actions you will find on the marketplace are: + +- [Actions for Discord](https://github.com/marketplace/actions/actions-for-discord) +- [GitHub Action for Slack](https://github.com/marketplace/actions/github-action-for-slack) +- [Jekyll action](https://github.com/marketplace/actions/jekyll-action) +- [Run Jest](https://github.com/marketplace/actions/run-jest) + +And that just scratches the surface of the 1600+ and counting actions you will find on the marketplace + +Follow [this guide](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/publishing-actions-in-github-marketplace#publishing-an-action) to learn how to publish your actions to the GitHub Marketplace + +### What's next? + +- [Take another GitHub Skills course](https://github.com/githubskills). +- [Read the GitHub Getting Started docs](https://docs.github.com/en/get-started). +- To find projects to contribute to, check out [GitHub Explore](https://github.com/explore). diff --git a/.github/steps/my-workflow.md b/.github/steps/my-workflow.md deleted file mode 100644 index e69de29..0000000 diff --git a/README.md b/README.md index 292ad7b..efb05e9 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,7 @@ +
+ - -
- -

Step 1: Initialize a new JavaScript project

 - -_Welcome to the course :tada:_ - -### Configuring a workflow - -Actions are enabled on your repository by default, but we still have to tell our repository to use them. We do this by creating a workflow file in our repository. - -A **workflow** file can be thought of as the recipe for automating a task. They house the start to finish instructions, in the form of `jobs` and `steps`, for what should happen based on specific triggers. - -Your repository can contain multiple **workflow** files that carry out a wide variety of tasks. It is important to consider this when deciding on a name for your **workflow**. The name you choose should reflect the tasks being performed. - -_In our case, we will use this one **workflow** file for many things, which leads us to break this convention for teaching purposes._ - -Read more about [workflows](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/configuring-a-workflow#choosing-the-type-of-actions-for-your-workflow) - -## On to your development environment - -Our JavaScript actions are going to leverage the [GitHub ToolKit](https://github.com/actions/toolkit) for developing GitHub Actions. - -This is an external library that we will install using `npm` which means that you will need [Node.js](https://nodejs.org/) installed. - -We find writing actions to be easier from a local environment vs trying to do everything right here in the repository. Doing these steps locally allows you to use the editor of your choice so that you have all the extensions and snippets you are used to when writing code. - -If you do not have a preferred environment then we suggest following along exactly as you see on the screen, which means you'll need to install [Visual Studio Code](https://code.visualstudio.com/). - -## Don't forget to set up your workstation - -Most of your work going forward will take place away from your Skills repository, so before continuing with the course ensure you have the following installed on your **local machine**. - -1. [ ] [Node.js](https://nodejs.org) -2. [ ] [Visual Studio Code](https://code.visualstudio.com/) or your editor of choice -3. [ ] [Git](https://git-scm.com/) - -### :keyboard: Activity 1: Initialize a new JavaScript project - -Once you have the necessary tools installed locally, follow these steps to begin creating your first action. - -1. Open the **Terminal** (Mac and Linux) or **Command Prompt** (Windows) on your local machine -2. Clone your Skills repo to your local machine: - ```shell - git clone .git - ``` -3. Navigate to the folder you just cloned: - ```shell - cd - ``` -4. We are using branch called `main`. - ```shell - git switch main - ``` -5. Create a new folder for our actions files: - ```shell - mkdir -p .github/actions/joke-action - ``` -6. Navigate to the `joke-action` folder you just created: - ```shell - cd .github/actions/joke-action - ``` -7. Initialize a new project: - ```shell - npm init -y - ``` -8. Install the **request**, **request-promise** and **@actions/core** dependencies using `npm` from the [GitHub ToolKit] (https://github.com/actions/toolkit): - ```shell - npm install --save request request-promise @actions/core - ``` -9. Commit those newly added files,we will remove the need to upload **node_modules** in a later step: - ```shell - git add . - git commit -m 'add project dependencies' - ``` -10. Push your changes to your repository: - ```shell - git push - ``` -11. Wait about 20 seconds then refresh this page for the next step. - - - -## Step 2: Configure Your Action - -_Let's keep going! :bike:_ - -### Excellent! - -Now that we have the custom action pre-requisites, let us create **joke-action** action. - -### :keyboard: Activity 1: Configure Your Action - -All of the following steps take place inside of the `.github/actions/joke-action` directory. - -We will start with using the parameters that are **required** and later implement some optional parameters as our action evolves. - -1. Create a new file in: `.github/actions/joke-action/action.yml` -2. Add the following contents to the `.github/actions/joke-action/action.yml` file: - ```yaml - name: "my joke action" - - description: "use an external API to retrieve and display a joke" - - runs: - using: "node16" - main: "main.js" - ``` -3. Save the `action.yml` file -4. Commit the changes and push them to the `main` branch: - ```shell - git add action.yml - git commit -m 'create action.yml' - git pull - git push - ``` -5. Wait about 20 seconds then refresh this page for the next step. - - - -## Step 3: Create the metadata file - -_Nice work configuring your action :smile:_ - -## Action metadata - -Every GitHub Action that we write needs to be accompanied by a metadata file. This file has a few rules to it, as are indicated below: - -- Filename **must** be `action.yml`. -- Required for both Docker container and JavaScript actions. -- Written in YAML syntax. - -This file defines the following information about your action: - -| Parameter | Description | Required | -| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | :----------------: | -| Name | The name of your action. Helps visually identify the actions in a job. | :white_check_mark: | -| Description | A summary of what your action does. | :white_check_mark: | -| Inputs | Input parameters allow you to specify data that the action expects to use during runtime. These parameters become environment variables in the runner. | :x: | -| Outputs | Specifies the data that subsequent actions can use later in the workflow after the action that defines these outputs has run. | :x: | -| Runs | The command to run when the action executes. | :white_check_mark: | -| Branding | You can use a color and Feather icon to create a badge to personalize and distinguish your action in GitHub Marketplace. | :x: | - ---- - -Read more about [Action metadata](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/metadata-syntax-for-github-actions) - -### :keyboard: Activity 1: Create the metadata file - -All of the following steps take place inside of the `.github/actions/joke-action` directory. - -Our action does not require much metadata for it to run correctly. We will not be accepting any inputs, we will however be setting a single output this time. - -1. Update the action metadata file `.github/actions/joke-action/action.yml` with the following content: - ```yaml - name: "my joke action" - - description: "use an external API to retrieve and display a joke" - - outputs: - joke-output: - description: The resulting joke from the icanhazdadjokes API - - runs: - using: "node16" - main: "main.js" - ``` -2. Save the `action.yml` file -3. Commit the changes and push them to GitHub: - ```shell - git add action.yml - git commit -m 'add metadata for the joke action' - git pull - git push - ``` -4. Wait about 20 seconds then refresh this page for the next step. - - - -## Step 4: Create the JavaScript files for your action - -_Good job adding the metadata file! :dancer:_ - -## Files - -As you probably know, in JavaScript and other programming languages it is common to break your code into modules so that it is easier to read and maintain going forward. Since JavaScript actions are just programs written in JavaScript that run based on a specific trigger we are able to make our action code modular as well. - -To do so we will create two files. One of them will contain the logic to reach out to an external API and retrieve a joke for us, the other will call that module and print the joke to the actions console for us. We will be extending this functionality in our third and final action. - -### Fetching a joke - -**Joke API** - - -The first file will be `joke.js` and it will fetch our joke for us. We will be using the [icanhazdadjoke API](https://icanhazdadjoke.com/api) for our action. This API does not require any authentication, but it does however that we set a few parameters in the [HTTP headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers). We need to point out what those are when we get to the code, however it is outside of the scope of this course to cover HTTP in any depth. - -When we make our request to this API we will get back a JSON Object in the response. That Object looks like this: - -``` -{ - id: '0LuXvkq4Muc', - joke: "I knew I shouldn't steal a mixer from work, but it was a whisk I was willing to take.", - status: 200 -} -``` - -It contains 3 key/value pairs of data that we can use in our own program or service. In our case, we are only interested in the `joke` field. - -**Joke Module** - -We will create a file named `joke.js` and it will reside in the `.github/action/joke-action` directory. - -The joke module will look like this: - -```javascript -const request = require("request-promise"); - -const options = { - method: "GET", - uri: "https://icanhazdadjoke.com/", - headers: { - Accept: "application/json", - "User-Agent": - "Writing JavaScript action GitHub Skills course." - }, - json: true -}; - -async function getJoke() { - const res = await request(options); - return res.joke; -} - -module.exports = getJoke; -``` - -
Need an advanced description of the joke.js source code? -We first bring in the `request-promise` library that we installed earlier using `npm`. - -Next we define a set of `options` that the `request-promise` library will use when it makes the request. - -Read more about [request-promise](https://github.com/request/request-promise/) - -Inside of the `options` block we add a key named `headers`. This defines the HTTP headers that the **icanhazdadjoke** API expects in each request that comes it's way. - -**icanhazdadjoke** cares the most about the keys, **Accept** and **User-Agent**, so we need to make sure we fill them in. - -Next we define an **asynchronous JavaScript function** to make the request for us, storing the JSON Object that is returned in a variable named `res`. - -Lastly, we `return` the `res.joke` which is only the value associated with the `joke` key of the JSON Object. This value will be random every time our action runs because of how we are interacting with the **icanhazdadjoke** API. - -This file finishes up by exporting the newly created function so that we can use it in our `main.js` file. - - - -### Creating the main entry point for your action - -**Main Module** - -We will also create a file named `main.js` that resides inside of the `.github/actions/joke-action` directory. - -That file will look like this: - -```javascript -const getJoke = require("./joke"); -const core = require("@actions/core"); - -async function run() { - const joke = await getJoke(); - console.log(joke); - core.setOutput("joke-output", joke); -} - -run(); -``` - -
Need an advanced description of the main.js source code? -Like we did in the `joke.js` file, we are first going to bring in our dependencies. Only this time, our dependencies include something we wrote! To do that we simply use `require()` to point to the location of the file we wish to bring in. - -We also bring in `@actions/core` so that we can set the output of our action. - -Next we write another **asynchronous JavaScript function** that stores the return value of `getJoke()` in a variable called **joke**. - -Then we log the joke to the console. - -Finally we finish the function with by setting the contents of the joke as the value of the `joke-output` output parameter. We will use this output later in the course. -_Don't forget to call the `run()` function._ - - - -### :keyboard: Activity 1: Creating the JavaScript files for your new action. - -1. Create and add the following contents to the `.github/actions/joke-action/joke.js` file: - - ```javascript - const request = require("request-promise"); - - const options = { - method: "GET", - uri: "https://icanhazdadjoke.com/", - headers: { - Accept: "application/json", - "User-Agent": - "Writing JavaScript action GitHub Skills course." - }, - json: true - }; - - async function getJoke() { - const res = await request(options); - return res.joke; - } - - module.exports = getJoke; - ``` - -2. Save the `joke.js` file. -3. Create and add the following contents to the `.github/actions/joke-action/main.js` file: - - ```javascript - const getJoke = require("./joke"); - const core = require("@actions/core"); - - async function run() { - const joke = await getJoke(); - console.log(joke); - core.setOutput("joke-output", joke); - } - - run(); - ``` - -4. Save the `main.js` file. -5. Commit the changes to this branch and push them to GitHub: - ```shell - git add joke.js main.js - git commit -m 'creating joke.js and main.js' - git pull - git push - ``` - - - -## Step 5: Add your action to the workflow file - -_Great job! :tada:_ - -All of the following steps will add the action to the workflow file that’s already in the repo [`my-workflow.yml` file](/.github/workflows/my-workflow.yml) - -### :keyboard: Activity 1: Edit the custom action at the bottom of the workflow file. - -```yaml - - name: ha-ha - uses: ./.github/actions/joke-action -``` - -Here is what the full file should look like (we’re using issues instead of the pull request event and removing the reference to the hello world action.) - -```yaml -name: JS Actions - -on: - issues: - types: [labeled] - -jobs: - action: - if: ${{ !github.event.repository.is_template }} - runs-on: ubuntu-latest - - steps: - - uses: actions/checkout@v3 - - name: ha-ha - uses: ./.github/actions/joke-action - -``` - -You can make these changes in your repository by opening [`my-workflow.yml`](/.github/workflows/my-workflow.yml) in another browser tab and [editing the file directly](https://docs.github.com/en/repositories/working-with-files/managing-files/editing-files). Make sure to select the `Commit directly to the main branch` option. - - - -
- -

Step 6: Trigger the joke action

 - -_Great job! :heart:_ - -Everything is all set up and now we are ready to start laughing. You will find you have some joke related labels available to you in this repository. You don't have to use them, any label will trigger our workflow, but the easiest way to follow along would be to use suggested labels. - -### Trigger a joke - -1. Open issue #1 in the "Issues tab" -2. Apply the `first-joke` label to the issue -3. Wait a few seconds and then apply the `second-joke` label to the issue -4. Check the `JS Actions` workflow results on the "Actions tab" - - - -## Finish - -celebrate - -### Congratulations, you've completed this course! - -In this course, you've learned a lot about developing custom actions using JavaScript and Actions Toolkit. - -## Publishing your actions - -Publishing your actions is a great way to help others in your team and across the GitHub community. Although actions do not need to be published to be consumed, by adding them to the marketplace you make them easier to find. - -Some notable actions you will find on the marketplace are: - -- [Actions for Discord](https://github.com/marketplace/actions/actions-for-discord) -- [GitHub Action for Slack](https://github.com/marketplace/actions/github-action-for-slack) -- [Jekyll action](https://github.com/marketplace/actions/jekyll-action) -- [Run Jest](https://github.com/marketplace/actions/run-jest) - -And that just scratches the surface of the 1600+ and counting actions you will find on the marketplace - -Follow [this guide](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/publishing-actions-in-github-marketplace#publishing-an-action) to learn how to publish your actions to the GitHub Marketplace - -### What's next? - -- [Take another GitHub Skills course](https://github.com/githubskills). -- [Read the GitHub Getting Started docs](https://docs.github.com/en/get-started). -- To find projects to contribute to, check out [GitHub Explore](https://github.com/explore). - - +
--- Get help: [Post in our discussion board](https://github.com/skills/.github/discussions) • [Review the GitHub status page](https://www.githubstatus.com/) © 2023 GitHub • [Code of Conduct](https://www.contributor-covenant.org/version/2/1/code_of_conduct/code_of_conduct.md) • [MIT License](https://gh.io/mit) + +
From 9422d2566232e72a4faa396614b053682a60dfe4 Mon Sep 17 00:00:00 2001 From: Kevin Heis Date: Tue, 30 May 2023 15:09:27 -0700 Subject: [PATCH 5/8] manual fixes --- .github/script/update-step.sh | 8 +------ .../steps/1-initialize-javascript-project.md | 4 +--- .../4-create-javascript-files-for-action.md | 6 +++-- .github/workflows/0-welcome.yml | 23 +++++++++---------- .../1-initialize-javascript-project.yml | 21 ++++++++--------- .github/workflows/2-configure-your-action.yml | 23 +++++++++---------- .github/workflows/3-create-metadata-file.yml | 23 +++++++++---------- .../4-create-javascript-files-for-action.yml | 21 ++++++++--------- .../5-add-action-to-workflow-file.yml | 21 ++++++++--------- .github/workflows/6-trigger-action.yml | 21 ++++++++--------- 10 files changed, 79 insertions(+), 92 deletions(-) diff --git a/.github/script/update-step.sh b/.github/script/update-step.sh index 70d79a2..21eb972 100755 --- a/.github/script/update-step.sh +++ b/.github/script/update-step.sh @@ -12,13 +12,7 @@ fi echo "Make sure we are on the main branch" git checkout main -echo "Remove 'open' from any
tags" -sed -r 's/
/
/g' README.md > tmp -mv tmp README.md - -echo "Add 'open' to step TO_STEP" -sed -r "s/
/
/g" README.md > tmp -mv tmp README.md +echo "TODO NEEDS UPDATE" echo "Update the step file to TO_STEP" echo "$TO_STEP" > .github/steps/-step.txt diff --git a/.github/steps/1-initialize-javascript-project.md b/.github/steps/1-initialize-javascript-project.md index 0e159ca..8712586 100644 --- a/.github/steps/1-initialize-javascript-project.md +++ b/.github/steps/1-initialize-javascript-project.md @@ -7,9 +7,7 @@ Encourage users to open new tabs for steps! --> -
- -

Step 1: Initialize a new JavaScript project

 +## Step 1: Initialize a new JavaScript project _Welcome to the course :tada:_ diff --git a/.github/steps/4-create-javascript-files-for-action.md b/.github/steps/4-create-javascript-files-for-action.md index 3e4830e..ed0417f 100644 --- a/.github/steps/4-create-javascript-files-for-action.md +++ b/.github/steps/4-create-javascript-files-for-action.md @@ -58,7 +58,8 @@ async function getJoke() { module.exports = getJoke; ``` -
Need an advanced description of the joke.js source code? +Need an advanced description of the joke.js source code? + We first bring in the `request-promise` library that we installed earlier using `npm`. Next we define a set of `options` that the `request-promise` library will use when it makes the request. @@ -98,7 +99,8 @@ async function run() { run(); ``` -
Need an advanced description of the main.js source code? +Need an advanced description of the main.js source code? + Like we did in the `joke.js` file, we are first going to bring in our dependencies. Only this time, our dependencies include something we wrote! To do that we simply use `require()` to point to the location of the file we wish to bring in. We also bring in `@actions/core` so that we can set the output of our action. diff --git a/.github/workflows/0-welcome.yml b/.github/workflows/0-welcome.yml index 12e4837..49ec9c1 100644 --- a/.github/workflows/0-welcome.yml +++ b/.github/workflows/0-welcome.yml @@ -1,6 +1,6 @@ name: Step 0, Welcome -# This step triggers after the learner creates a new repository from the template +# This step triggers after the learner creates a new repository from the template. # This workflow updates from step 0 to step 1. # When creating a repository from a template, there is variability in the @@ -36,27 +36,27 @@ jobs: needs: get_current_step # We will only run this action when: - # 1. This repository isn't the template repository - # 2. The step is currently 0 + # 1. This repository isn't the template repository. + # 2. The step is currently 0. # Reference: https://docs.github.com/en/actions/learn-github-actions/contexts # Reference: https://docs.github.com/en/actions/learn-github-actions/expressions if: >- ${{ !github.event.repository.is_template && needs.get_current_step.outputs.current_step == 0 }} - # We'll run Ubuntu for performance instead of Mac or Windows + # We'll run Ubuntu for performance instead of Mac or Windows. runs-on: ubuntu-latest steps: - # We'll need to check out the repository so that we can edit the README - # We'll need to check out the repository so that we can edit the README + # We'll need to check out the repository so that we can edit the README. + # We'll need to check out the repository so that we can edit the README. - name: Checkout uses: actions/checkout@v3 with: fetch-depth: 0 # Let's get all the branches - # This is required to establish labels - # after being created from the template repository + # This is required to establish labels. + # after being created from the template repository. - name: Prepare labels run: | echo "Make sure we are on step 0" @@ -72,8 +72,8 @@ jobs: env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - # This is required to create issues - # after being created from the template repository + # This is required to create issues. + # after being created from the template repository. - name: Prepare issues run: | echo "Make sure we are on step 0" @@ -87,8 +87,7 @@ jobs: env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - # Update README to close
- # and open
+ # Update README from step 0 to step 1. - name: Update to step 1 uses: skills/action-update-step@v2 with: diff --git a/.github/workflows/1-initialize-javascript-project.yml b/.github/workflows/1-initialize-javascript-project.yml index c118d03..13125b5 100644 --- a/.github/workflows/1-initialize-javascript-project.yml +++ b/.github/workflows/1-initialize-javascript-project.yml @@ -1,9 +1,9 @@ name: Step 1, Initialize JavaScript Project -# This step listens for the learner pushing a commit to `main` +# This step listens for the learner pushing a commit to `main`. # This workflow updates from step 1 to step 2. -# This will run every time we push a commit to `main` +# This will run every time we push a commit to `main`. # Reference: https://docs.github.com/en/actions/learn-github-actions/events-that-trigger-workflows on: @@ -13,8 +13,8 @@ on: - main permissions: - # Need `contents: read` to checkout the repository - # Need `contents: write` to update the step metadata + # Need `contents: read` to checkout the repository. + # Need `contents: write` to update the step metadata. contents: write jobs: @@ -36,36 +36,35 @@ jobs: needs: get_current_step # We will only run this action when: - # 1. This repository isn't the template repository - # 2. The step is currently 1 + # 1. This repository isn't the template repository. + # 2. The step is currently 1. # Reference: https://docs.github.com/en/actions/learn-github-actions/contexts # Reference: https://docs.github.com/en/actions/learn-github-actions/expressions if: >- ${{ !github.event.repository.is_template && needs.get_current_step.outputs.current_step == 1 }} - # We'll run Ubuntu for performance instead of Mac or Windows + # We'll run Ubuntu for performance instead of Mac or Windows. runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v3 with: - fetch-depth: 0 # Let's get all the branches + fetch-depth: 0 # Let's get all the branches. - name: Dump GitHub comment context id: github_comment_step run: echo '${{ toJSON(github.event) }}' - # Check if NPM package.json exists in the expected location + # Check if NPM package.json exists in the expected location. - name: Check file existence id: check_files uses: andstor/file-existence-action@v2 with: files: ".github/actions/joke-action/package.json" - # Update README to close
- # and open
+ # Update README from step 1 to step 2. - name: Update to step 2 if: steps.check_files.outputs.files_exists == 'true' uses: skills/action-update-step@v2 diff --git a/.github/workflows/2-configure-your-action.yml b/.github/workflows/2-configure-your-action.yml index 4d6bafe..4555aa1 100644 --- a/.github/workflows/2-configure-your-action.yml +++ b/.github/workflows/2-configure-your-action.yml @@ -1,9 +1,9 @@ name: Step 2, Configure Your Action -# This step listens for the learner pushing a commit to `main` +# This step listens for the learner pushing a commit to `main`. # This workflow updates from step 2 to step 3. -# This will run every time we push a commit to `main` +# This will run every time we push a commit to `main`. # Reference: https://docs.github.com/en/actions/learn-github-actions/events-that-trigger-workflows on: workflow_dispatch: @@ -12,8 +12,8 @@ on: - main permissions: - # Need `contents: read` to checkout the repository - # Need `contents: write` to update the step metadata + # Need `contents: read` to checkout the repository. + # Need `contents: write` to update the step metadata. contents: write jobs: @@ -35,37 +35,36 @@ jobs: needs: get_current_step # We will only run this action when: - # 1. This repository isn't the template repository - # 2. The step is currently 2 + # 1. This repository isn't the template repository. + # 2. The step is currently 2. # Reference: https://docs.github.com/en/actions/learn-github-actions/contexts # Reference: https://docs.github.com/en/actions/learn-github-actions/expressions if: >- ${{ !github.event.repository.is_template && needs.get_current_step.outputs.current_step == 2 }} - # We'll run Ubuntu for performance instead of Mac or Windows + # We'll run Ubuntu for performance instead of Mac or Windows. runs-on: ubuntu-latest steps: - # We'll need to check out the repository so that we can edit the README + # We'll need to check out the repository so that we can edit the README. - name: Checkout uses: actions/checkout@v3 with: - fetch-depth: 0 # Let's get all the branches + fetch-depth: 0 # Let's get all the branches. - name: Dump GitHub comment context id: github_comment_step run: echo '${{ toJSON(github.event) }}' - # Check if NPM package.json exists in the expected location + # Check if NPM package.json exists in the expected location. - name: Check file existence id: check_files uses: andstor/file-existence-action@v2 with: files: ".github/actions/joke-action/action.yml" - # Update README to close
- # and open
+ # Update README from step 2 to step 3. - name: Update to step 3 if: steps.check_files.outputs.files_exists == 'true' uses: skills/action-update-step@v2 diff --git a/.github/workflows/3-create-metadata-file.yml b/.github/workflows/3-create-metadata-file.yml index caaceb5..5a57d32 100644 --- a/.github/workflows/3-create-metadata-file.yml +++ b/.github/workflows/3-create-metadata-file.yml @@ -1,9 +1,9 @@ name: Step 3, Create Metadata File -# This step listens for the learner pushing a commit to `main` +# This step listens for the learner pushing a commit to `main`. # This workflow updates from step 3 to step 4. -# This will run every time we push a commit to `main` +# This will run every time we push a commit to `main`. # Reference: https://docs.github.com/en/actions/learn-github-actions/events-that-trigger-workflows on: workflow_dispatch: @@ -11,8 +11,8 @@ on: branches: [main] permissions: - # Need `contents: read` to checkout the repository - # Need `contents: write` to update the step metadata + # Need `contents: read` to checkout the repository. + # Need `contents: write` to update the step metadata. contents: write env: @@ -37,37 +37,36 @@ jobs: needs: get_current_step # We will only run this action when: - # 1. This repository isn't the template repository - # 2. The step is currently 3 + # 1. This repository isn't the template repository. + # 2. The step is currently 3. # Reference: https://docs.github.com/en/actions/learn-github-actions/contexts # Reference: https://docs.github.com/en/actions/learn-github-actions/expressions if: >- ${{ !github.event.repository.is_template && needs.get_current_step.outputs.current_step == 3 }} - # We'll run Ubuntu for performance instead of Mac or Windows + # We'll run Ubuntu for performance instead of Mac or Windows. runs-on: ubuntu-latest steps: - # We'll need to check out the repository so that we can edit the README + # We'll need to check out the repository so that we can edit the README. - name: Checkout uses: actions/checkout@v3 with: - fetch-depth: 0 # Let's get all the branches + fetch-depth: 0 # Let's get all the branches. - name: Dump GitHub comment context id: github_comment_step run: echo '${{ toJSON(github.event) }}' - # Check if action.yml file contains metadata + # Check if action.yml file contains metadata. - name: Read action file contents id: read_action_yml_file uses: andstor/file-reader-action@v1 with: path: ".github/actions/joke-action/action.yml" - # Update README to close
- # and open
+ # Update README to from step 3 to step 4. - name: Update to step 4 if: (contains(steps.read_action_yml_file.outputs.contents, ${{ env.EXPECTED_METADATA }}) uses: skills/action-update-step@v2 diff --git a/.github/workflows/4-create-javascript-files-for-action.yml b/.github/workflows/4-create-javascript-files-for-action.yml index 0f6d60f..790eca0 100644 --- a/.github/workflows/4-create-javascript-files-for-action.yml +++ b/.github/workflows/4-create-javascript-files-for-action.yml @@ -1,6 +1,6 @@ name: Step 4, Create JavaScript Files For Action -# This step listens for the learner pushing a commit to `main` +# This step listens for the learner pushing a commit to `main`. # This workflow updates from step 4 to step 5. # This will run every time we push a commit to `main` @@ -11,8 +11,8 @@ on: branches: [main] permissions: - # Need `contents: read` to checkout the repository - # Need `contents: write` to update the step metadata + # Need `contents: read` to checkout the repository. + # Need `contents: write` to update the step metadata. contents: write jobs: @@ -34,37 +34,36 @@ jobs: needs: get_current_step # We will only run this action when: - # 1. This repository isn't the template repository - # 2. The step is currently 4 + # 1. This repository isn't the template repository. + # 2. The step is currently 4. # Reference: https://docs.github.com/en/actions/learn-github-actions/contexts # Reference: https://docs.github.com/en/actions/learn-github-actions/expressions if: >- ${{ !github.event.repository.is_template && needs.get_current_step.outputs.current_step == 4 }} - # We'll run Ubuntu for performance instead of Mac or Windows + # We'll run Ubuntu for performance instead of Mac or Windows. runs-on: ubuntu-latest steps: - # We'll need to check out the repository so that we can edit the README + # We'll need to check out the repository so that we can edit the README. - name: Checkout uses: actions/checkout@v3 with: - fetch-depth: 0 # Let's get all the branches + fetch-depth: 0 # Let's get all the branches. - name: Dump GitHub comment context id: github_comment_step run: echo '${{ toJSON(github.event) }}' - # Check if actin JavaScript exists in the expected location + # Check if action JavaScript exists in the expected location. - name: Check file existence id: check_files uses: andstor/file-existence-action@v2 with: files: ".github/actions/joke-action/joke.js, .github/actions/joke-action/main.js" - # Update README to close
- # and open
+ # Update README from step 4 to step 5. - name: Update to step 5 if: steps.check_files.outputs.files_exists == 'true' uses: skills/action-update-step@v2 diff --git a/.github/workflows/5-add-action-to-workflow-file.yml b/.github/workflows/5-add-action-to-workflow-file.yml index 17845c4..df9e715 100644 --- a/.github/workflows/5-add-action-to-workflow-file.yml +++ b/.github/workflows/5-add-action-to-workflow-file.yml @@ -3,7 +3,7 @@ name: Step 5, Add Action To Workflow File # This step listens for the learner pushing a commit to `main` # This workflow updates from step 5 to step 6. -# This will run every time we push a commit to `main` +# This will run every time we push a commit to `main`. # Reference: https://docs.github.com/en/actions/learn-github-actions/events-that-trigger-workflows on: workflow_dispatch: @@ -11,8 +11,8 @@ on: branches: [main] permissions: - # Need `contents: read` to checkout the repository - # Need `contents: write` to update the step metadata + # Need `contents: read` to checkout the repository. + # Need `contents: write` to update the step metadata. contents: write env: @@ -37,37 +37,36 @@ jobs: needs: get_current_step # We will only run this action when: - # 1. This repository isn't the template repository - # 2. The step is currently 5 + # 1. This repository isn't the template repository. + # 2. The step is currently 5. # Reference: https://docs.github.com/en/actions/learn-github-actions/contexts # Reference: https://docs.github.com/en/actions/learn-github-actions/expressions if: >- ${{ !github.event.repository.is_template && needs.get_current_step.outputs.current_step == 5 }} - # We'll run Ubuntu for performance instead of Mac or Windows + # We'll run Ubuntu for performance instead of Mac or Windows. runs-on: ubuntu-latest steps: - # We'll need to check out the repository so that we can edit the README + # We'll need to check out the repository so that we can edit the README. - name: Checkout uses: actions/checkout@v3 with: - fetch-depth: 0 # Let's get all the branches + fetch-depth: 0 # Let's get all the branches. - name: Dump GitHub comment context id: github_comment_step run: echo '${{ toJSON(github.event) }}' - # Check if action.yml file contains metadata + # Check if action.yml file contains metadata. - name: Read action file contents id: read_action_yml_file uses: andstor/file-reader-action@v1 with: path: ".github/workflows/my-workflow.yml" - # Update README to close
- # and open
+ # Update README from step 5 to step 6. - name: Update to step 6 if: (contains(steps.read_action_yml_file.outputs.contents, ${{ env.EXPECTED_METADATA }}) uses: skills/action-update-step@v2 diff --git a/.github/workflows/6-trigger-action.yml b/.github/workflows/6-trigger-action.yml index f4783de..f47dd16 100644 --- a/.github/workflows/6-trigger-action.yml +++ b/.github/workflows/6-trigger-action.yml @@ -1,9 +1,9 @@ name: Step 6, Trigger Your Action -# This step listens for the learner applying a label to an issue +# This step listens for the learner applying a label to an issue. # This workflow updates from step to step X. -# This will run every time we apply a label to an issue +# This will run every time we apply a label to an issue. # Reference: https://docs.github.com/en/actions/learn-github-actions/events-that-trigger-workflows on: workflow_dispatch: @@ -11,8 +11,8 @@ on: types: [labeled] permissions: - # Need `contents: read` to checkout the repository - # Need `contents: write` to update the step metadata + # Need `contents: read` to checkout the repository. + # Need `contents: write` to update the step metadata. contents: write env: @@ -37,30 +37,29 @@ jobs: needs: get_current_step # We will only run this action when: - # 1. This repository isn't the template repository - # 2. The step is currently 6 + # 1. This repository isn't the template repository. + # 2. The step is currently 6. # Reference: https://docs.github.com/en/actions/learn-github-actions/contexts # Reference: https://docs.github.com/en/actions/learn-github-actions/expressions if: >- ${{ !github.event.repository.is_template && needs.get_current_step.outputs.current_step == 6 }} - # We'll run Ubuntu for performance instead of Mac or Windows + # We'll run Ubuntu for performance instead of Mac or Windows. runs-on: ubuntu-latest steps: - # We'll need to check out the repository so that we can edit the README + # We'll need to check out the repository so that we can edit the README. - name: Checkout uses: actions/checkout@v3 with: - fetch-depth: 0 # Let's get all the branches + fetch-depth: 0 # Let's get all the branches. - name: Dump GitHub comment context id: github_comment_step run: echo '${{ toJSON(github.event) }}' - # Update README to close
- # and open
+ # Update README from step 6 to step X. - name: Update to step X if: contains(github.event, ${{ env.EXPECTED_METADATA }}) uses: skills/action-update-step@v2 From 9787e2dc5ef6b9fa2b6d24babbe32e741ae395cb Mon Sep 17 00:00:00 2001 From: Kevin Heis Date: Tue, 30 May 2023 15:24:38 -0700 Subject: [PATCH 6/8] manual fixes --- .github/workflows/0-welcome.yml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/.github/workflows/0-welcome.yml b/.github/workflows/0-welcome.yml index 49ec9c1..461eb80 100644 --- a/.github/workflows/0-welcome.yml +++ b/.github/workflows/0-welcome.yml @@ -48,12 +48,11 @@ jobs: runs-on: ubuntu-latest steps: - # We'll need to check out the repository so that we can edit the README. # We'll need to check out the repository so that we can edit the README. - name: Checkout uses: actions/checkout@v3 with: - fetch-depth: 0 # Let's get all the branches + fetch-depth: 0 # Let's get all the branches. # This is required to establish labels. # after being created from the template repository. From 60d87cc0bc7657d8b480cdb6b26be53177feaca4 Mon Sep 17 00:00:00 2001 From: Kevin Heis Date: Tue, 30 May 2023 15:26:48 -0700 Subject: [PATCH 7/8] manual fixes --- .../steps/1-initialize-javascript-project.md | 1 - .github/steps/2-configure-your-action.md | 6 +++--- .github/steps/3-create-metadata-file.md | 12 +++++------ .../4-create-javascript-files-for-action.md | 20 +++++-------------- .../steps/5-add-action-to-workflow-file.md | 10 +++------- .github/steps/X-finish.md | 1 - .github/workflows/0-welcome.yml | 10 +++++----- .../1-initialize-javascript-project.yml | 8 ++++---- .github/workflows/2-configure-your-action.yml | 8 ++++---- .github/workflows/3-create-metadata-file.yml | 8 ++++---- .../4-create-javascript-files-for-action.yml | 8 ++++---- .../5-add-action-to-workflow-file.yml | 8 ++++---- .github/workflows/6-trigger-action.yml | 6 +++--- 13 files changed, 45 insertions(+), 61 deletions(-) diff --git a/.github/steps/1-initialize-javascript-project.md b/.github/steps/1-initialize-javascript-project.md index 8712586..fa538a3 100644 --- a/.github/steps/1-initialize-javascript-project.md +++ b/.github/steps/1-initialize-javascript-project.md @@ -1,4 +1,3 @@ -