Action three

Two actions down, one more to go! Before we move on with building our final action let's take a second to do a quick recap since this lesson has thrown a lot of information at you.

The workflow
We started out by explaining what a workflow is and how it pertains to the GitHub Actions platform. You learned about how a defined event sets your workflow orchestra in motion.

You learned about runners, jobs, steps and have dabbled in the syntax of a workflow file at every step in this course. I don't want to spoil too much here, but you'll be doing it again in this one as well 😉.

Action metadata
You learned that every action is accompanied by an action.yml file which contains a series of metadata for how the action behaves. This file defines all of an actions inputs, outputs, runtime environment, name, description and even branding.

Hello action
Your first JavaScript action took the traditional path of a "Hello World" introduction. You ended up expanding that action to accept inputs to help make it a little more dynamic. Ultimately, the key takeaway was to understand that you can pass input that is defined in the workflow to an action as long as the action's metadata supports it.

When consuming or creating actions it is incredibly helpful to take care to understand that actions metadata file.

Joke action
You second JavaScript action demonstrated that your workflow environment is capable of communicating outside of it's own network. We reached out to an external API and used that information to set outputs for another action to consume. As with inputs your actions metadata must support the ability to set outputs if you want to use this option.

What next?
Your third, and final, JavaScript action of this course is going to use yet another library from the Actions ToolKit. It is also going to consume the outputs of your joke action and use them to help create issues in your repository.

We need to make some edits to the my-workflow.yml file to get it configured to use this final action.

⌨️ Activity: Final workflow edit

1. Edit your my-workflow.yml file to contain the following:

   name: JS Actions
   
   on:
     pull_request:
       types: [labeled]
   
   jobs:
     action:
       runs-on: ubuntu-latest
   
       steps:
         - uses: actions/checkout@v1
   
         - name: hello-action
           uses: ./.github/actions/hello-world
   
         - name: ha-ha
           uses: ./.github/actions/joke-action
           id: jokes
   
         - name: create-issue
           uses: ./.github/actions/issue-maker
           with:
             repo-token: ${{secrets.GITHUB_TOKEN}}
             joke: ${{steps.jokes.outputs.joke-output}}

2. Commit the changes to a new branch, you can name it action-three.
3. Create a pull request named Use outputs

---

Like our other actions, I'll respond in the new pull request when I detect it has been opened.

Who's there?

GitHub Actions... thats who!

The next action we write is going to reach out to an external API and fetch data for consumption. Although your action is bound to a step, which is bound to a workflow within your repository it is NOT bound to an isolated network. This means that we can leverage APIs from our favorite cloud providers, favorite pizza shops, social media or whatever API our developers need.

What is an API

If you ask this question to anyone in the industry you'll likely get the obvious answer of "Application Programming Interface", which although true, doesn't exactly explain what one is or does.

Let's do a thought experiment to help understand the concept of an API.

I think most people are familiar with a car 🚗 either through personal experience or some form of media. I also think it's safe to say that most people understand the concepts behind driving a car. By examining how we drive a car we can understand how APIs work in a fun way.

Car Components
When driving a car there are a few components of the car that the driver interacts with directly. This wont be an all inclusive list, and each car varies to some degree, but so does each API. We will use the following components for our example:

• Gas pedal
• Brake pedal
• Steering wheel
• Gear shift

As the driver of the car when we push one of the pedals, move the gear shift position or turn the steering wheel the car responds. Most of us don't know exactly how it responds though. We actually don't even think about the system that is in place to amplify the force applied to the steering wheel when we make a turn. We probably don't know if our vehicle has a hydraulic, electro-hydraulic or fully electric power steering system. What we do know is that when we turn the steering wheel the car responds by turning.

The steering wheel has become an API between the driver and the inner workings of the power steering system and the systems that it communicates with. You see, steering the car eventually turns the wheels of the car and that takes place through further interconnected systems that are abstracted away from the driver.

The same is true with the gear shift. When we move our car into a different state using the gear shift a series of events take place throughout the car to reflect that change. This could be going from a stopped position to driving forward. It could be going from forward motion to reverse. It could even be cycling through gears in the case of a manual transmission. Ultimately, by moving the gear shift we tell the car what to do when we apply the gas pedal.

Very simply the gas pedal changes the speed of our car. We press it down to go faster or lift pressure off of it to stop going faster. What about if we want to fully stop? The gas pedal, gear shift and steering wheel wont exactly help us do that, hence the need for a brake pedal.

All of these systems, these APIs designed to help a human drive a car, are constantly communicating with one another to produce a moving vehicle. The driver didn't have to concern themselves with the implementation, platform, architecture, complex queries or manufacturer differences of each car. No, the driver just needed to concern themselves with how a steering wheel, gas pedal, brake pedal and gear shift work.

What gets even better is that the API for a car is pretty standard from one car to the next. Once you learn one steering wheel you pretty much know them all!

Standard API Types:

This concept is also prevalent in real world APIs. There are many standard types of APIs and if you understand each standard then you ultimately understand how to use that API to your advantage.

The most common types of API at the time this course was written are:

• REST
• SOAP
• XML-RPC
• JSON-RPC

Going into detail about each standard is beyond the scope of this course, however it's important to understand that there are many standards out there. Although there are many standards the purpose of each API is to give your program or service the ability to communicate easily with another program or service without the need to know the implementation details.

APIs also give you, the developer, the ability to give others access to specific functionality or resources within your own program or service.

📺 Watch this 30 second video on APIs

What about our action?

We are now going to write an action that reaches out to a service through its REST API to get us a random joke. We will then display that joke on the Actions tab.

For our purposes the API we use will not require authentication, however that is a limitation of the course content and not the GitHub Actions platform. If you need to store secrets, like API keys, for your workflow to use you will need to configure secrets as inputs.

We are also going to demonstrate having multiple files make up an action as well as importing other external libraries for your action to use.

What are we waiting for, let's get started 😉

On to your development environment

@eky5006 our JavaScript actions are going to leverage the GitHub ToolKit for developing GitHub Actions.

This is an external library that we will install using npm which means that you will need Node.js installed.

I 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 I suggest following along with me exactly as you see on the screen, which means you'll need to install Visual Studio Code.

Don't forget to set up your workstation 😉

Most of your work going forward will take place away from your Learning Lab repository, so before continuing with the course ensure you have the following installed on your local machine.

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

⌨️ Activity: 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 Learning Lab repo to your local machine:

   git clone https://github.com/eky5006/writing-javascript-actions.git

3. Navigate to the folder you just cloned:

   cd writing-javascript-actions

4. Create a new branch named hello-world. This is the branch we will use to write our first action. Please do not capitalize letters unless I do, I run case-sensitive checks to make sure I can help you along the way!

   git checkout -b hello-world

5. Create a new folder for our actions files:

   mkdir -p .github/actions/hello-world

6. Navigate to the hello-world folder you just created:

   cd .github/actions/hello-world

7. Initialize a new project:

   npm init -y

8. Install the core dependency from the GitHub ToolKit:

   npm install --save @actions/core

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

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

10. Push your changes to your repository:

    git push -u origin hello-world

---

I will respond once you have finished.

Great job!

You did it 🎉

You have successfully written three different JavaScript actions.

Let's take a quick look at all the things you learned in this course:

Workflows
Along the way you learned a little about workflows and how to configure them. You managed to accomplish all these things:

• Define two different event triggers
• Filter an event trigger to run only when a label is added to a pull request
• You configured one unique job containing three unique steps within a workflow
• You learned how to overwrite default action values by defining them in a workflow
• One of your steps consumed a secret
• One of your steps consumed the output of a previous step

That's quite a bit for a course that doesn't cover workflows!

Action metadata

• You became familiar with over 1/2 of the syntax keywords that can be used in an action.yml file
• Using inputs: and outputs: allowed you to create more dynamic and reusable metadata files for your actions.
• You've mow written the metadata for three different actions

JavaScript actions
Wow, what a series of tasks! You started with the traditional hello world in the console, which was then expanded to use the input: parameters specified in the actions metadata. Through the use of that metadata you were able to be flexible with your greeting.

You learned how GitHub Actions behave when consuming external APIs and you also used the response from an external API as an output: parameter for a later step in the workflow.

Lastly you saw how to use actions to interact with a repository by creating an issue containing a joke.

You used multiple packages in your action source code, you consumed inputs: and set outputs:.

You learned how to use the @actions/core package to write errors and terminate a misbehaving action.

At this point you are armed with everything you need to know to go out there and begin creating your own custom JavaScript actions.

We aren't done yet 😉

Throughout this course I have promised to show you how to get rid of the node_modules folder in your repository.

I also want to take a few minutes to point you to the information you need to place your own custom actions on the GitHub Marketplace for others to use.

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

⌨️ Activity: Create a pull request to prepare the repository for actions

1. Create a new workflow file titled my-workflow.yml inside of the folders .github/workflows/ by using the instructions below, or this quicklink.
   • Go to the Actions tab.
   • Choose the Set up a workflow yourself option, located on the top right hand corner of the screen.
   • Change the name of the file to .github/workflows/my-workflow.yml.
2. Commit the workflow to a new branch, you can name it add-initial-workflow.
3. Create a pull request titled Create a workflow.
4. Supply the pull request body content and click Create pull request.

It is important to place meaningful content into the body of the pull requests you create throughout this course. This repository will stay with you long after you complete the course. It is advisable that you use the body of the pull requests you create as a way to take long lived notes about thing you want to remember.

Suggested body content

Workflow files are the recipe for task automation. This is where actions are placed if I want to use them for a task.

I'll respond in the new pull request when I detect it has been created.

---

If at any point you're expecting a response and don't see one, refresh the page.