Introduction

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 therandom-number output variable, and runs a script namedgoodbye.sh.

Once you complete this project, you should understand how to build your own composite action and test it in a workflow.

Composite actions and reusable workflows

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重複の回避.

Prerequisites

Before you begin, you'll create a repository on GitHub.

1. Create a new public repository on GitHub. You can choose any repository name, or use the followinghello-world-composite-action example. You can add these files after your project has been pushed to GitHub. For more information, see新しいリポジトリの作成.

2. Clone your repository to your computer. For more information, seeリポジトリをクローンする.

3. From your terminal, change directories into your new repository.

   Shell

   cd hello-world-composite-action

4. In thehello-world-composite-action repository, create a new file calledgoodbye.sh with example code:

   Shell

   echo "echo Goodbye" > goodbye.sh

5. From your terminal, makegoodbye.sh executable.

   Shell

   chmod +x goodbye.sh

   Shell

   chmod +x goodbye.sh

   Shell

   git add --chmod=+x -- goodbye.sh

6. From your terminal, check in yourgoodbye.sh file.

   Shell

   git add goodbye.shgit commit -m "Add goodbye script"git push

   Shell

   git add goodbye.shgit commit -m "Add goodbye script"git push

   Shell

   git commit -m "Add goodbye script"git push

Creating an action metadata file

1. In thehello-world-composite-action repository, create a new file calledaction.yml and add the following example code. For more information about this syntax, seeMetadata syntax reference.

   YAML

   name:'Hello World'description:'Greet someone'inputs:who-to-greet:# id of inputdescription:'Who to greet'required:truedefault:'World'outputs:random-number:description:"Random number"value:${{steps.random-number-generator.outputs.random-number}}runs:using:"composite"steps:-name:SetGreetingrun:echo"Hello $INPUT_WHO_TO_GREET."shell:bashenv:INPUT_WHO_TO_GREET:${{inputs.who-to-greet}}-name:RandomNumberGeneratorid:random-number-generatorrun:echo"random-number=$(echo $RANDOM)">>$GITHUB_OUTPUTshell:bash-name:SetGitHubPathrun:echo"$GITHUB_ACTION_PATH">>$GITHUB_PATHshell:bashenv:GITHUB_ACTION_PATH:${{github.action_path}}-name:Rungoodbye.shrun:goodbye.shshell:bash

   This file defines thewho-to-greet input, maps the random generated number to therandom-number output variable, adds the action's path to the runner system path (to locate thegoodbye.sh script during execution), and runs thegoodbye.sh script.

   For more information about managing outputs, seeMetadata syntax reference.

   For more information about how to usegithub.action_path, seeContexts reference.

2. From your terminal, check in youraction.yml file.

   Shell

   git add action.ymlgit commit -m "Add action"git push

3. From your terminal, add a tag. This example uses a tag calledv1. For more information, seeカスタム アクションについて.

   Shell

   git tag -a -m "Description of this release" v1git push --follow-tags

Testing out your action in a workflow

The following workflow code uses the completed hello world action that you made inCreating a composite action.

Copy the workflow code into a.github/workflows/main.yml file in another repository, replacingOWNER andSHA with the repository owner and the SHA of the commit you want to use, respectively. You can also replace thewho-to-greet input with your name.

on: [push]jobs:  hello_world_job:    runs-on: ubuntu-latest    name: A job to say hello    steps:      - uses: actions/checkout@v4      - id: foo        uses: OWNER/hello-world-composite-action@SHA        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-latestname:Ajobtosayhellosteps:-uses:actions/checkout@v4-id:foouses:OWNER/hello-world-composite-action@SHAwith:who-to-greet:'Mona the Octocat'-run:echorandom-number"$RANDOM_NUMBER"shell:bashenv:RANDOM_NUMBER:${{steps.foo.outputs.random-number}}

From your repository, click theActions 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.

Creating a composite action within the same repository

1. Create a new subfolder calledhello-world-composite-action, this can be placed in any subfolder within the repository. However, it is recommended that this be placed in the.github/actions subfolder to make organization easier.

2. In thehello-world-composite-action folder, do the same steps to create thegoodbye.sh script

   Shell

   echo "echo Goodbye" > goodbye.sh

   Shell

   chmod +x goodbye.sh

   Shell

   chmod +x goodbye.sh

   Shell

   git add --chmod=+x -- goodbye.sh

   Shell

   git add goodbye.shgit commit -m "Add goodbye script"git push

   Shell

   git add goodbye.shgit commit -m "Add goodbye script"git push

   Shell

   git commit -m "Add goodbye script"git push

3. In thehello-world-composite-action folder, create theaction.yml file based on the steps inCreating a composite action.

4. When using the action, use the relative path to the folder where the composite action'saction.yml file is located in theuses key. The below example assumes it is in the.github/actions/hello-world-composite-action folder.

on: [push]jobs:  hello_world_job:    runs-on: ubuntu-latest    name: A job to say hello    steps:      - uses: actions/checkout@v4      - id: foo        uses: ./.github/actions/hello-world-composite-action        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-latestname:Ajobtosayhellosteps:-uses:actions/checkout@v4-id:foouses:./.github/actions/hello-world-composite-actionwith:who-to-greet:'Mona the Octocat'-run:echorandom-number"$RANDOM_NUMBER"shell:bashenv:RANDOM_NUMBER:${{steps.foo.outputs.random-number}}

Example composite actions on GitHub

You can find many examples of composite actions on GitHub.

• microsoft/action-python
• microsoft/gpt-review
• tailscale/github-action