In this guide, you'll learn about the basic components needed to create and use a packaged composite action. To focus this guide on the components needed to package the action, the functionality of the action's code is minimal. The action prints "Hello World" and then "Goodbye", or if you provide a custom name, it prints "Hello [who-to-greet]" and then "Goodbye". The action also maps a random number to the
random-number
output variable, and runs a script named
goodbye.sh
.
Once you complete this project, you should understand how to build your own composite action and test it in a workflow.
Warning:
When creating workflows and actions, you should always consider whether your code might execute untrusted input from possible attackers. Certain contexts should be treated as untrusted input, as an attacker could insert their own malicious content. For more information, see "
Security hardening for GitHub Actions
."
Composite actions allow you to collect a series of workflow job steps into a single action which you can then run as a single job step in multiple workflows. Reusable workflows provide another way of avoiding duplication, by allowing you to run a complete workflow from within other workflows. For more information, see "
Avoiding duplication
."
Before you begin, you'll create a repository on GitHub.com.
-
Create a new public repository on GitHub.com. You can choose any repository name, or use the following
hello-world-composite-action
example. You can add these files after your project has been pushed to GitHub. For more information, see "
Creating a new repository
."
-
Clone your repository to your computer. For more information, see "
Cloning a repository
."
-
From your terminal, change directories into your new repository.
Shell
cd hello-world-composite-action
cd hello-world-composite-action
-
In the
hello-world-composite-action
repository, create a new file called
goodbye.sh
with example code:
Shell
echo "echo Goodbye" > goodbye.sh
echo "echo Goodbye" > goodbye.sh
-
From your terminal, make
goodbye.sh
executable.
-
From your terminal, check in your
goodbye.sh
file.
-
In the
hello-world-composite-action
repository, create a new file called
action.yml
and add the following example code. For more information about this syntax, see "
Metadata syntax for GitHub Actions
".
YAML
name: 'Hello World'
description: 'Greet someone'
inputs:
who-to-greet: # id of input
description: 'Who to greet'
required: true
default: 'World'
outputs:
random-number:
description: "Random number"
value: ${{ steps.random-number-generator.outputs.random-number }}
runs:
using: "composite"
steps:
- name: Set Greeting
run: echo "Hello $INPUT_WHO_TO_GREET."
shell: bash
env:
INPUT_WHO_TO_GREET: ${{ inputs.who-to-greet }}
- name: Random Number Generator
id: random-number-generator
run: echo "random-number=$(echo $RANDOM)" >> $GITHUB_OUTPUT
shell: bash
- name: Set GitHub Path
run: echo "$GITHUB_ACTION_PATH" >> $GITHUB_PATH
shell: bash
env:
GITHUB_ACTION_PATH: ${{ github.action_path }}
- name: Run goodbye.sh
run: goodbye.sh
shell: bash
name:
'Hello World'
description:
'Greet someone'
inputs:
who-to-greet:
description:
'Who to greet'
required:
true
default:
'World'
outputs:
random-number:
description:
"Random number"
value:
${{
steps.random-number-generator.outputs.random-number
}}
runs:
using:
"composite"
steps:
-
name:
Set
Greeting
run:
echo
"Hello $INPUT_WHO_TO_GREET."
shell:
bash
env:
INPUT_WHO_TO_GREET:
${{
inputs.who-to-greet
}}
-
name:
Random
Number
Generator
id:
random-number-generator
run:
echo
"random-number=$(echo $RANDOM)"
>>
$GITHUB_OUTPUT
shell:
bash
-
name:
Set
GitHub
Path
run:
echo
"$GITHUB_ACTION_PATH"
>>
$GITHUB_PATH
shell:
bash
env:
GITHUB_ACTION_PATH:
${{
github.action_path
}}
-
name:
Run
goodbye.sh
run:
goodbye.sh
shell:
bash
This file defines the
who-to-greet
input, maps the random generated number to the
random-number
output variable, adds the action's path to the runner system path (to locate the
goodbye.sh
script during execution), and runs the
goodbye.sh
script.
For more information about managing outputs, see "
Metadata syntax for GitHub Actions
".
For more information about how to use
github.action_path
, see "
Contexts
".
-
From your terminal, check in your
action.yml
file.
Shell
git add action.yml
git commit -m "Add action"
git push
git add action.yml
git commit -m "Add action"
git push
-
From your terminal, add a tag. This example uses a tag called
v1
. For more information, see "
About custom actions
."
Shell
git tag -a -m "Description of this release" v1
git push --follow-tags
git tag -a -m "Description of this release" v1
git push --follow-tags
The following workflow code uses the completed hello world action that you made in "
Creating a composite action
".
Copy the workflow code into a
.github/workflows/main.yml
file in another repository, but replace
actions/hello-world-composite-action@v1
with the repository and tag you created. You can also replace the
who-to-greet
input with your name.
YAML
on: [push]
jobs:
hello_world_job:
runs-on: ubuntu-latest
name: A job to say hello
steps:
- uses: actions/checkout@v4
- id: foo
uses: actions/hello-world-composite-action@v1
with:
who-to-greet: 'Mona the Octocat'
- run: echo random-number "$RANDOM_NUMBER"
shell: bash
env:
RANDOM_NUMBER: ${{ steps.foo.outputs.random-number }}
on:
[
push
]
jobs:
hello_world_job:
runs-on:
ubuntu-latest
name:
A
job
to
say
hello
steps:
-
uses:
actions/checkout@v4
-
id:
foo
uses:
actions/hello-world-composite-action@v1
with:
who-to-greet:
'Mona the Octocat'
-
run:
echo
random-number
"$RANDOM_NUMBER"
shell:
bash
env:
RANDOM_NUMBER:
${{
steps.foo.outputs.random-number
}}
From your repository, click the
Actions
tab, and select the latest workflow run. The output should include: "Hello Mona the Octocat", the result of the "Goodbye" script, and a random number.
You can find many examples of composite actions on GitHub.com.