Creating a composite action

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.

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 Vermeiden von Duplikaten.

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

1. Create a new public repository on . 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 . For more information, see Ein neues Repository erstellen.

2. Clone your repository to your computer. For more information, see Ein Repository klonen.

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

   Shell

   cd hello-world-composite-action
   

4. In the hello-world-composite-action repository, create a new file called goodbye.sh with example code:

   Shell

   echo "echo Goodbye" > goodbye.sh
   

5. From your terminal, make goodbye.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 your goodbye.sh file.

   Shell

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

   Shell

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

   Shell

   git commit -m "Add goodbye script"
   git push
   

1. 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 Metadatensyntax für 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)" >> $_OUTPUT
         shell: bash
   
       - name: Set  Path
         run: echo "$_ACTION_PATH" >> $_PATH
         shell: bash
         env:
           _ACTION_PATH: ${{ .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 Metadatensyntax für Actions.

   For more information about how to use .action_path, see Zugreifen auf kontextbezogene Informationen zu Workflowausführungen.

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

   Shell

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

3. From your terminal, add a tag. This example uses a tag called v1. For more information, see Informationen zu benutzerdefinierten Aktionen.

   Shell

   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 ./workflows/main.yml file in another repository, replacing OWNER and SHA with the repository owner and the SHA of the commit you want to use, respectively. You can also replace the who-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-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 }}

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.

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

2. In the hello-world-composite-action folder, do the same steps to create the goodbye.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.sh
   git commit -m "Add goodbye script"
   git push
   

   Shell

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

   Shell

   git commit -m "Add goodbye script"
   git push
   

3. In the hello-world-composite-action folder, create the action.yml file based on the steps in Creating a composite action.

4. When using the action, use the relative path to the folder where the composite action's action.yml file is located in the uses key. The below example assumes it is in the ./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: ././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-latest
    name: A job to say hello
    steps:
      - uses: actions/checkout@v4
      - id: foo
        uses: ././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 }}

You can find many examples of composite actions on .

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