---

name: github-actions-composite description: Creates GitHub Actions composite actions. Use when building reusable action.yml files, integrating github-script, or setting up action inputs/outputs.

GitHub Actions Composite Actions

Composite actions bundle multiple workflow steps into a reusable action.yml file. Use composite actions when orchestrating shell commands, calling other actions, or adding JavaScript via github-script. This guide covers composite actions only (not JavaScript or Docker actions).

action.yml Structure

Minimal Example

Copyname: 'Greet User'
description: 'Greets a user by name'

inputs:
  name:
    description: 'Name to greet'
    required: true

outputs:
  greeting:
    description: 'The greeting message'
    value: ${{ steps.greet.outputs.greeting }}

runs:
  using: "composite"
  steps:
    - id: greet
      shell: bash
      run: |
        MESSAGE="Hello, ${{ inputs.name }}!"
        echo "greeting=$MESSAGE" >> "$GITHUB_OUTPUT"

Step Properties

Using Other Actions

Composite actions can call other actions with uses:

Copysteps:
  - uses: actions/checkout@<pinned sha> # <version tag>
    with:
      fetch-depth: 0

  - uses: actions/setup-node@<pinned sha> # <version tag>
    with:
      node-version: '24'

  - id: build
    shell: bash
    run: npm run build

The called action runs in the composite action's context. Pass required inputs explicitly.

Using github-script

Use actions/github-script to run JavaScript within composite actions for GitHub API access.

Available Objects

Basic Usage

Copy- uses: actions/github-script@<pinned sha> # <version tag>
  with:
    script: |
      const { data: pr } = await github.rest.pulls.get({
        owner: context.repo.owner,
        repo: context.repo.repo,
        pull_number: context.issue.number
      });
      core.setOutput('title', pr.title);

SECURITY: Use Environment Variables for Inputs

Never interpolate untrusted input directly into the script:

Copy# UNSAFE - vulnerable to script injection
- uses: actions/github-script@<pinned sha> # <version tag>
  with:
    script: |
      const title = "${{ inputs.title }}";  // DANGEROUS

# SAFE - use environment variables
- uses: actions/github-script@<pinned sha> # <version tag>
  env:
    TITLE: ${{ inputs.title }}
  with:
    script: |
      const title = process.env.TITLE;  // Safe
      core.info(`Processing: ${title}`);

Returning Values

Return values are available as steps.<id>.outputs.result:

Copy- id: get-version
  uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7.0.1
  with:
    result-encoding: string
    script: |
      const pkg = require('./package.json');
      return pkg.version;

- shell: bash
  run: echo "Version is ${{ steps.get-version.outputs.result }}"

Security Best Practices

ALWAYS Pin Actions to Full Commit SHAs

Always pin actions to full commit SHAs. No exceptions. Tags and versions can be moved to malicious code at any time:

Copy# UNSAFE - tag can be moved
- uses: actions/checkout@v4

# SAFE - immutable commit reference
- uses: actions/checkout@<pinned sha> # <version tag>

Use npx pin-github-action to automatically pin actions to their current SHAs:

Copynpx pin-github-action .github/actions/my-action/action.yml

Environment Variables for Untrusted Input

Expression syntax (${{ }}) is evaluated before the shell runs:

Copy# VULNERABLE - if inputs.filename contains: foo; rm -rf /
- shell: bash
  run: cat ${{ inputs.filename }}

# SAFE - shell handles the variable
- shell: bash
  env:
    FILENAME: ${{ inputs.filename }}
  run: cat "$FILENAME"

Input Validation

Validate inputs at the start of your action:

Copy- shell: bash
  env:
    INPUT_MODE: ${{ inputs.mode }}
  run: |
    if [[ ! "$INPUT_MODE" =~ ^(create|update|delete)$ ]]; then
      echo "::error::Invalid mode: $INPUT_MODE. Must be create, update, or delete."
      exit 1
    fi

Document Required Permissions

In your action's README, document minimum required permissions:

Copy# Required workflow permissions:
# permissions:
#   contents: read
#   pull-requests: write

Common Patterns

Conditional Steps

Copy- if: ${{ inputs.skip-tests != 'true' }}
  shell: bash
  run: npm test

Multi-line Scripts with Outputs

Copy- id: extract
  shell: bash
  run: |
    VERSION=$(cat VERSION)
    echo "version=$VERSION" >> "$GITHUB_OUTPUT"

Passing Outputs to Action Output

Copyoutputs:
  version:
    description: 'Extracted version'
    value: ${{ steps.extract.outputs.version }}

Default Input Values

Copyinputs:
  node-version:
    description: 'Node.js version'
    required: false
    default: '20'

Working Directory

Copy- shell: bash
  working-directory: ./packages/core
  run: npm install

File Locations

Workflow

• Create action.yml in repo root or .github/actions/<name>/
• Set name, description, and runs.using: "composite"
• Define inputs with descriptions (mark required ones)
• Define outputs referencing step outputs
• Add steps with explicit shell for all run commands
• Pin ALL external actions to full commit SHAs (no exceptions)
• Use environment variables for untrusted input
• Validate inputs at action start
• Document required permissions in README