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"