In this article, we will be diving into the world of GitHub Actions, exploring the basics of this powerful automation tool. Whether you are a beginner or an experienced developer, you will find that GitHub Actions is a valuable tool to have in your arsenal.
What is GitHub Actions?
GitHub Actions is a feature provided by GitHub that allows users to automate their software development workflows, including building, testing, and deploying code. With GitHub Actions, you can create custom automated processes that run whenever specific events occur in a GitHub repository. For example, you can configure a workflow that automatically builds and deploys your code whenever you push changes to a specific branch.
So, after this brief explanation, let's jump to the GitHub Actions features.
Workflow Files
A workflow file specifies the steps that should be taken to automate any task, like building, testing, and deploying your code or even sending an sms when someone opens a pull request.
The workflow files are composed of Events, Jobs, Runners, Steps and Actions.
Events
Events are the triggers for the workflow, they are what needs to happen for this workflow to fire and run the automated work.
Events are defined in the yaml
workflow file by passing the on
property.
Examples of events:
- PR Created
- Push
- Issue Created
- Collaborator Join
- PR Merged
And you can specify branches, statuses, tags and paths to specifically limit the trigger to the desired event.
I recommend reading the documentation to know all existing events.
Jobs
Jobs group a set of steps that will be executed. After the Worflow is triggered, it will run all the jobs presented on it.
Inside the job we need to specified the runs-on
property, that correspond to the enviroment this job will run, most commom is ubuntu-latest
.
Steps
Each step in a job represents a single task that should be performed. The steps can be defined using either an action or a command-line command.
An action is called using the uses
property, and its parameters are passed to the action through the with
property. Alternatively, a command-line command can be executed using the run
property.
Heres an example of an workflow.yaml
file:
name: Test Workflow
on:
push: # Push event
branches: # On branches
- 'releases/**'
- 'master'
jobs:
hello_world: # Define the job
runs-on: ubuntu-latest # Specify the runner to run the job on
name: Lint code
steps:
- name: Run Linter
uses: github/super-linter@v3 # Use Github Super Linter repository
with: # Input fot the action
some_api_key: ${{ secrets.api_key }} # Get the API key from repository secrets
- name: Print IPv4 # Some random command
run: ifconfig -a # Run ifconfig command
⚠️ In order for your Workflow file to work correctly, it needs to be placed inside the /.github/workflows
path within your repository.
-root
-.github
-workflows
your_worflow_file.yaml
Once you've set up a workflow file within your repository, there's nothing left to do but code!
Actions Files
The actions are a pre-packaged set of instructions that perform a specific task. Whether you create your own custom actions or use actions from the GitHub Actions Marketplace, you can easily integrate them into your workflows using YAML files.
Actions are defined in a action.yaml
file and must be stored in the root directory of your repository. It is recommended to store actions that will be used by third-parties or across multiple projects in a separate, dedicated repository that is publicly accessible. This ensures that the action is easily accessible and reusable by others.
Actions files are formed by name, description, inputs and runner.
Inputs
The inputs section defines the data needed to perform this action, which must be provided in the workflow that invokes them as mentioned earlier.
Runs
The runs section specifies the runtime environment for the action (example: Node.js version 12), and the main entry point for the action (example: dist/index.js).
Here´s an example:
name: "My Custom Action"
description: "A custom action for doing something cool."
inputs:
input1:
description: "The first input for the action."
required: true
input2:
description: "The second input for the action."
required: false
input3:
description: "The third input for the action."
required: false
...
runs:
using: "node12"
main: "dist/index.js"
Main file
The main file used in an action is typically a script file that is executed when the action is triggered in a workflow. The script file can be written in a variety of programming languages, such as JavaScript, Python, or Ruby.
Here is an example of a JavaScript script that could be used as the main file in an action:
const core = require('@actions/core');
const exec = require('@actions/exec');
async function run() {
try {
const command = core.getInput('command');
console.log(`Running command: ${command}`);
await exec.exec(command);
} catch (error) {
core.setFailed(error.message);
}
}
run();
Note that i used the @actions/core
and @actions/exec
, these libraries are part of the GitHub Actions Toolkit, a collection of libraries and tools provided by GitHub to simplify the development of custom actions for GitHub Actions.
The actual implementation of your main file will depend on the requirements of your action and the tools and services that you are integrating with.
Illustration
To summarize, I found this image on the internet that excellently illustrates the hierarchy within GitHub Actions, showing all the components discussed and their interrelationships. It serves as a visual representation of the concepts covered in this article and I believe it can help to better visualize how it works.
Thank you for reading this far and I hope it helped you understand a little more about this incredible feature on GitHub! 😊
Top comments (0)