Creating a GitHub Action: A Step‐by‐Step Guide - krdheeraj51/aws-labs GitHub Wiki

GitHub Actions automate tasks within your software development workflow. This post will guide you through creating a basic GitHub Action, explaining each part of the workflow file.

1. Setting up the Workflow File

Workflows are defined in YAML files within the .github/workflows directory of your repository.
Create a new file, for example, learn-github-actions.yml, inside the .github/workflows directory.

2. Basic Structure and Triggering Events

name: Learn GitHub Actions
run-name: ${{ github.actor }} is learning GitHub Actions
on: [push]
jobs:
check-bats-version:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '20'
- run: npm install -g bats
- run: bats -v

name: An optional name for your workflow, which appears on the "Actions" tab of your repository. If omitted, the filename is used.
run-name: Optional name for workflow runs, displaying in the workflow runs list, and can include dynamic content using GitHub context.
on: Specifies the trigger for the workflow. In this case, the workflow is triggered on every push to the repository.
- You can specify multiple events to trigger the workflow. For example:
```
on: [push, fork]
```
  This triggers the workflow on either a push or a fork event.
- To trigger the workflow on specific branches, use the following:
```
on:
  push:
    branches: [ "main" ]
```
  This will trigger the workflow only when changes are pushed to the main branch.

Advanced Triggering Options * Activity Types: Some events can be further customized with activity types. For example, the issues event can specify types like opened or labeled:

    ```
    on:
      issues:
        types:
          - opened
          - labeled
    ```

    With this setup, the workflow triggers when an issue is either opened or labeled.

3. Defining Jobs

jobs: Groups together all the jobs that will run in the workflow.
- check-bats-version: Defines a job named check-bats-version. Child keys define the properties of the job.
- runs-on: Configures the job to run on a virtual machine runner. ubuntu-latest specifies the latest version of Ubuntu Linux. This means the job runs on a fresh virtual machine hosted by GitHub.

4. Steps in a Job

steps: Groups together all the steps that run in the job. Each item nested under this section is a separate action or shell script.
- uses: actions/checkout@v4: The uses keyword specifies that this step will run v4 of the actions/checkout action. This action checks out your repository onto the runner, allowing you to run scripts or other actions against your code.
- uses: actions/setup-node@v4: This step uses the actions/setup-node@v4 action to install a specified version of Node.js (version 20 in this example). This puts both the node and npm commands in your PATH.
- run: npm install -g bats: The run keyword tells the job to execute a command on the runner. In this case, npm is used to install the bats software testing package.
- run: bats -v: This executes the bats command with a parameter that outputs the software version.

5. Committing and Pushing

Commit the changes to your repository.
Push the changes to your GitHub repository. The workflow will run automatically each time someone pushes a change to the repository.

6. Understanding Actions

An action is a reusable extension that simplifies your workflow. It is a custom application for the GitHub Actions platform that performs a complex but frequently repeated task.
You can write your own actions or use actions from the GitHub Marketplace.

With this basic setup, you can create powerful automated workflows to streamline your development process.