If you recall, a workflow file is the interface between you and the underlying actions in use to accomplish your desired tasks.
It is here where you supply inputs and consume outputs of an action. This is where the implementation details of the supplied information are abstracted away from you by the developer of the action.
But what if you're the one who writes the action 🤔?
Why to write your own actions
- Compliance constraints: If you are unable to use open-source actions, or need to ensure your workflows fall within standards that you are bound to, writing your own actions ensures you stay in compliance while still making the most out of this feature.
- Stability needs: Some fear with community driven actions is that their development processes may not be thorough, the developers will introduce changes that break your workflow or they may just give up on the project when you desperately need a feature added to the action. It is good practice to vet any and all community actions before consuming them!
- Action doesn't exist yet: Sometimes actions that solve your problem don't exist just yet. Or if they do exist they don't provide the functionality you may need.
- Privacy is paramount: You have a highly custom, highly proprietary repository and you need to keep your workflow and other automation just as guarded.
The two types of actions
Currently there are two types of actions that exist:
| JavaScript Actions | Docker Container Actions |
|---|---|
|
|
Location, location, location...
Great, you've decided you need or want to write a custom action and you've settle on the type of action that fits your needs best, so where do you place the source code for your action?
This question comes down to two main factors:
- Is this a public action that the community can use?
- Is this a private action used only by this repository?
If your action is meant to be public then it is recommended that the source code for the action resides in a repository of its own. This allows for the action to be easily versioned and provides better discoverability to the GitHub community.
If your action is meant to be private you can place it in any location within the repository you plan to use it in. GitHub recommends using the .github folder for this. For example .github/action/my-custom-action
If you plan to publicly share your action, we recommend creating a README file to help people learn how to use your action.
Each action is a mixture of some key files. Each action you write must contain the following files:
Action metadata
This file must be present for both JavaScript and Docker Container actions. It must be named action.yml or action.yaml.
It is responsible for creating the interface between the source code of the action and the workflow file the end-user is going to fill it.
We will talk in-depth about the action metadata file in a later section.
Action source code
This is the actual logic behind what you want your action to do. GitHub has created quite a few development tools to help with writing custom actions. It is not mandatory to use these tools if you want to create your own action, but they are nice to have 😄!
Dockerfile for Docker container actions only
If you have settled on writing a Docker container action, that action will require an accompanying Dockerfile.
Later, we will write one of each type of action to help demonstrate how these files work together.
👈 Before we dive more into writing our own actions, let's explore some examples of custom actions in use