[Github actions][actions]

Custom GitHub Actions: Core File Organization and Guidelines

Custom GitHub Actions enable users to define specific workflows tailored to their needs. Below are the core conventions and best practices for organizing custom GitHub Actions.

---

0. Installed images in github acitons environment

https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2404-Readme.md

---

1. Folder Organization

Each custom Action must reside in its own folder, typically under .github/actions:

.github/
  actions/
    action-name/          # Custom Action folder
      action.yml          # Core configuration file (required)
      script.sh           # Optional: Supporting script file
      Dockerfile          # Optional: Docker configuration file
      index.js            # Optional: Entry point for JavaScript Actions
      README.md           # Optional: Action documentation

---

2. Core File: action.yml

action.yml is the required configuration file that defines the Action's behavior.

Required Fields

• name: The Action's name (for identification).
• description: A short description of the Action's purpose.
• inputs: (Optional) Parameters to pass to the Action.
• outputs: (Optional) Values returned by the Action.
• runs: Specifies how the Action should execute.

---

3. Types of Actions

(1) Composite Actions

A series of steps defined directly in the action.yml file.

Example: action.yml

name: My Composite Action
description: A composite Action example
inputs:
  example_input:
    description: "An example input"
    required: true
runs:
  using: "composite"
  steps:
    - name: Print input
      run: echo "Input is ${{ inputs.example_input }}"

---

(2) JavaScript/TypeScript Actions

Runs on Node.js, allowing complex logic and dependencies.

File Structure:

.github/actions/my-js-action/
  action.yml
  index.js            # Main script file
  package.json        # Node.js dependencies

Example: action.yml

name: My JavaScript Action
description: A JavaScript Action example
inputs:
  example_input:
    description: "An example input"
    required: true
runs:
  using: "node16"
  main: index.js       # Entry point

---

(3) Docker Actions

Runs inside a Docker container with a custom environment.

File Structure:

.github/actions/my-docker-action/
  action.yml
  Dockerfile          # Required for Docker Actions

Example: action.yml

name: My Docker Action
description: A Docker Action example
inputs:
  example_input:
    description: "An example input"
    required: true
runs:
  using: "docker"
  image: "Dockerfile"
  args:
    - ${{ inputs.example_input }}

Example: Dockerfile

FROM ubuntu:20.04
RUN apt-get update && apt-get install -y curl jq
COPY entrypoint.sh /entrypoint.sh
ENTRYPOINT ["/entrypoint.sh"]

---

4. Optional Files

README.md

• Provides documentation for the Action, including:
  • Description of functionality.
  • List of input and output parameters.
  • Examples of usage.

Scripts

• Include additional shell or Python scripts as needed to support the Action's logic.

---

5. Referencing Custom Actions

(1) Local Repository

If the Action is in the same repository:

- name: Use Custom Action
  uses: ./github/actions/action-name
  with:
    example_input: "Hello World"

(2) External Repository

If the Action is hosted in another public repository:

- name: Use Custom Action
  uses: username/repository-name/path/to/action-name@v1
  with:
    example_input: "Hello World"

---

6. Best Practices

1. File Naming

   • The configuration file must be named action.yml or action.yaml.
   • For Docker Actions, a Dockerfile is required.

2. Dependencies

   • For JavaScript Actions, declare all dependencies in package.json.
   • For Docker Actions, include all required tools in the Dockerfile.

3. Checkout Repository

   • Always include actions/checkout before referencing local Actions to load the repository's content.

---

7. Example Workflow Using a Custom Action

Workflow File: .github/workflows/main.yml

name: Example Workflow

on:
  push:
    branches:
      - main

jobs:
  example:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Code
        uses: actions/checkout@v3

      - name: Use Custom Action
        uses: ./github/actions/action-name
        with:
          example_input: "Hello World"