Closed github-learning-lab[bot] closed 2 years ago
Earlier you learned how the different pieces of GitHub Actions work together. Now you will learn about the components that make up an individual action.
Remember, an action is the unit of work that a workflow file executes when it reaches that task. They are called by referencing them as the value to the uses:
key in a workflow step.
Docker actions consist of three key components:
Component | Description |
---|---|
Action source code files | These files contain the logic of your action. This includes any dependencies or custom modules that your main logic may need. |
Action metadata file | This file contains information that the actions source code can use. An example of this is allowing a developer to specify an API key as an input variable for your action to consume. This file MUST be named action.yml |
Dockerfile | This file defines the environment and dependencies for the action. It is best practice that this file be named Dockerfile |
workflow.yml
, is the user facing component. It must be housed in .github/workflows/
and doesn't need to be called workflow.yml
, but its essence is a workflow. This is what we interact with directly when we want to supply input, or consume the output of a given action. You can think of workflow.yml
as a user-interface for the action.yml
file.action.yml
, is the interface between the user and the source code of the action. It is housed in a directory just for the action. This file may contain default values for inputs and outputs that the source code relies on. Those values can be overwritten by the workflow.yml
file, but their default values live here and allow the action to execute properly if no values are supplied. This file also defines a high-level environment for the source code, such as whether to use Docker or Node.js and the execution entry point.Dockerfile
is only needed when creating Docker based actions and it is responsible for packaging up the environment as well as the source code for the given action. It is housed in a directory just for the action. This file is read and a Docker image is created from it. Once the image is created a container is created from the image and the action is executed.Although the workflow file is used to allow us to set the inputs
and outputs
using the with:
keyword it is not a required component of an individual action.
The failing workflow
You may be following along on the Actions tab of this repository. If you are, you'll notice that the workflow we set up previously is failing. That is the currently expected behavior: we referenced an action in the hello-world
directory, which doesn't yet exist. We will be fixing that as we move forward with the lesson.
Since every GitHub Action that we write needs to be accompanied by a metadata file this is the file we will create first.
This file has a few rules to it, lets outline those now:
action.yml
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. | β |
Outputs | Specifies the data that subsequent actions can use later in the workflow after the action that defines these outputs has run. | β |
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. | β |
πRead more about Action metadata
Now that we know what action metadata is, let's create the metadata for our hello-world action.
action.yml
file and add necessary metadataπ‘All of the following steps take place inside of the .github/actions/hello-world
directory.
We will start with using the parameters that are required and later implement some optional parameters as our action knowledge grows.
Create and add the following contents to the .github/actions/hello-world/action.yml
file:
You can use this link to easily create this file.
name: "my hello action"
description: "say hello with GitHub Actions"
runs:
using: "docker"
image: "Dockerfile"
Commit the changes to a new branch named hello-world
Create a pull request titled Add a Hello World action.
Supply the pull request body content and click Create pull request
.
I'll respond when you create a new pull request.
I have created a new pull request where we will continue this lesson. Click the link to meet me over there.
In the meantime I have closed this issue since we wont be needing it anymore π
Hello world with Docker π³
@kng72 we are going to start with the typical "Hello World" example and build something more complex after, but first let's decide if a Docker based action is the right action for us!
Why use Docker when writing GitHub Actions?
That's a super great question to ask. Before we talk about the components that make up Docker based actions, we should understand the good and the bad of Docker based actions.
Got it, what now?
Let's begin by exploring the components of a Docker based action and discuss how they fit together!