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 is 6 steps long and takes about 1 to 2 hours to be completed.

1. Right-clickStart course and open the link in a new tab.
   
2. In the new tab, follow the prompts to create a new repository.
   • For owner, choose your personal account or an organization to host the repository.
   • We recommend creating a public repository—private repositories willuse Actions minutes.
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.

Welcome to the course 🎉

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.

Aworkflow file can be thought of as the recipe for automating a task. They house the start to finish instructions, in the form ofjobs andsteps, for what should happen based on specific triggers.

Your repository can contain multipleworkflow files that carry out a wide variety of tasks. It is important to consider this when deciding on a name for yourworkflow. The name you choose should reflect the tasks being performed.

In our case, we will use this oneworkflow file for many things, which leads us to break this convention for teaching purposes.

Read more aboutworkflows

Our JavaScript actions are going to leverage theGitHub ToolKit for developing GitHub Actions.

This is an external library that we will install usingnpm which means that you will needNode.js 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 installVisual Studio Code.

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 yourlocal machine.

1. Node.js
2. Visual Studio Code or your editor of choice
3. Git

Once you have the necessary tools installed locally, follow these steps to begin creating your first action.

1. Open theTerminal (Mac and Linux) orCommand Prompt (Windows) on your local machine
2. Clone your Skills repo to your local machine:

   git clone<this repository URL>.git

3. Navigate to the folder you just cloned:

   cd<local folder with cloned repo>

4. We are using branch calledmain.

   git switch main

5. Create a new folder for our actions files:

   mkdir -p .github/actions/joke-action

6. Navigate to thejoke-action folder you just created:

   cd .github/actions/joke-action

7. Initialize a new project:

   npm init -y

8. Install therequest,request-promise and@actions/core dependencies usingnpm from the [GitHub ToolKit] (https://github.com/actions/toolkit):

   npm install --save request request-promise @actions/core

9. Commit those newly added files,we will remove the need to uploadnode_modules in a later step:

   git add.git commit -m'add project dependencies'

10. Push your changes to your repository:

    git push

11. Wait about 20 seconds then refresh this page for the next step.

Let's keep going! 🚲

Now that we have the custom action pre-requisites, let us createjoke-action action.

All of the following steps take place inside of the.github/actions/joke-action directory.

We will start with using the parameters that arerequired 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:

   name:"my joke action"description:"use an external API to retrieve and display a joke"runs:using:"node16"main:"main.js"

3. Save theaction.yml file
4. Commit the changes and push them to themain branch:

   git add action.ymlgit commit -m'create action.yml'git pullgit push

5. Wait about 20 seconds then refresh this page for the next step.

Nice working configuring your action 😄

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:

• Filenamemust beaction.yml.
• Required for both Docker container and JavaScript actions.
• Written in YAML syntax.

This file defines the following information about your action:

Read more aboutAction metadata

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:

   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 APIruns:using:"node16"main:"main.js"

2. Save theaction.yml file
3. Commit the changes and push them to GitHub:

   git add action.ymlgit commit -m'add metadata for the joke action'git pullgit push

4. Wait about 20 seconds then refresh this page for the next step.

Good job adding the metadata file! 💃

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.

Joke API

The first file will bejoke.js and it will fetch our joke for us. We will be using theicanhazdadjoke API for our action. This API does not require any authentication, but it does however that we set a few parameters in theHTTP 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 thejoke field.

Joke Module

We will create a file namedjoke.js and it will reside in the.github/action/joke-action directory.

The joke module will look like this:

constrequest=require("request-promise");constoptions={method:"GET",uri:"https://icanhazdadjoke.com/",headers:{Accept:"application/json","User-Agent":"Writing JavaScript action GitHub Skills course."},json:true};asyncfunctiongetJoke(){constres=awaitrequest(options);returnres.joke;}module.exports=getJoke;

Main Module

We will also create a file namedmain.js that resides inside of the.github/actions/joke-action directory.

That file will look like this:

constgetJoke=require("./joke");constcore=require("@actions/core");asyncfunctionrun(){constjoke=awaitgetJoke();console.log(joke);core.setOutput("joke-output",joke);}run();

1. Create and add the following contents to the.github/actions/joke-action/joke.js file:

   constrequest=require("request-promise");constoptions={method:"GET",uri:"https://icanhazdadjoke.com/",headers:{Accept:"application/json","User-Agent":"Writing JavaScript action GitHub Skills course."},json:true};asyncfunctiongetJoke(){constres=awaitrequest(options);returnres.joke;}module.exports=getJoke;

2. Save thejoke.js file.

3. Create and add the following contents to the.github/actions/joke-action/main.js file:

   constgetJoke=require("./joke");constcore=require("@actions/core");asyncfunctionrun(){constjoke=awaitgetJoke();console.log(joke);core.setOutput("joke-output",joke);}run();

4. Save themain.js file.

5. Commit the changes to this branch and push them to GitHub:

   git add joke.js main.jsgit commit -m'creating joke.js and main.js'git pullgit push

Great job! 🎉

All of the following steps will add the action to the workflow file that’s already in the repomy-workflow.yml file

      -name:ha-hauses:./.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.)

name:JS Actionson:issues:types:[labeled]jobs:action:if:${{ !github.event.repository.is_template }}runs-on:ubuntu-lateststeps:      -uses:actions/checkout@v3      -name:ha-hauses:./.github/actions/joke-action

You can make these changes in your repository by openingmy-workflow.yml in another browser tab andediting the file directly. Make sure to select theCommit directly to the main branch option.

Great job! ❤️

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.

1. Open issue #1 in the "Issues tab"
2. Apply thefirst-joke label to the issue
3. Wait a few seconds and then apply thesecond-joke label to the issue
4. Check theJS Actions workflow results on the "Actions tab"

In this course, you've learned a lot about developing custom actions using JavaScript and Actions Toolkit.

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
• GitHub Action for Slack
• Jekyll action
• Run Jest

And that just scratches the surface of the 1600+ and counting actions you will find on the marketplace

Followthis guide to learn how to publish your actions to the GitHub Marketplace

• Take another GitHub Skills course.
• Read the GitHub Getting Started docs.
• To find projects to contribute to, check outGitHub Explore.