GitHub Action: Docker Compose Action

---

Overview

This action runs your compose file(s) and clean up before action finished

Action

The action will run docker compose up to start the services defined in the given compose file(s). The compose file(s) can be specified using the compose-file input. Some extra options can be passed to the docker compose up command using the up-flags input.

Post hook

On post hook, the action will run docker compose down to clean up the services.

Logs of the Docker Compose services are logged using GitHub core.ts API before the cleanup. The log level can be set using the services-log-level input. The default is debug, which will only print logs if debug mode is switched on.

Some extra options can be passed to the docker compose down command using the down-flags input.

Usage

- uses: hoverkraft-tech/compose-action@3846bcd61da338e9eaaf83e7ed0234a12b099b72 # v2.4.1
  with:
    # Additional options to pass to `docker` command.
    docker-flags: ""

    # Path to compose file(s). It can be a list of files. It can be absolute or relative to the current working directory (cwd).
    # Default: `./docker-compose.yml`
    compose-file: ./docker-compose.yml

    # Services to perform `docker compose up`.
    services: ""

    # Additional options to pass to `docker compose up` command.
    up-flags: ""

    # Additional options to pass to `docker compose down` command.
    down-flags: ""

    # Additional options to pass to `docker compose` command.
    compose-flags: ""

    # Current working directory
    # Default: `${{ github.workspace }}`
    cwd: ${{ github.workspace }}

    # Compose version to use.
    # If null (default), it will use the current installed version.
    # If "latest", it will install the latest version.
    compose-version: ""

    # The log level used for Docker Compose service logs.
    # Can be one of "debug", "info".
    #
    # Default: `debug`
    services-log-level: debug

    # The GitHub token used to create an authenticated client (to fetch the latest version of Docker Compose).
    # Default: `${{ github.token }}`
    github-token: ${{ github.token }}

Inputs

Input	Description	Required	Default
docker-flags	Additional options to pass to docker command.	false	-
compose-file	Path to compose file(s). It can be a list of files. It can be absolute or relative to the current working directory (cwd).	false	./docker-compose.yml
services	Services to perform docker compose up.	false	-
up-flags	Additional options to pass to docker compose up command.	false	-
down-flags	Additional options to pass to docker compose down command.	false	-
compose-flags	Additional options to pass to docker compose command.	false	-
cwd	Current working directory	false	$\{\{ github.workspace }}
compose-version	Compose version to use.	false	-
	If null (default), it will use the current installed version.
	If "latest", it will install the latest version.
services-log-level	The log level used for Docker Compose service logs.	false	debug
	Can be one of "debug", "info".
github-token	The GitHub token used to create an authenticated client (to fetch the latest version of Docker Compose).	false	$\{\{ github.token }}

Examples

Example using in a full workflow

name: Docker Compose Action

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/[email protected]

      - name: Run docker compose
        uses: hoverkraft-tech/compose-action@3846bcd61da338e9eaaf83e7ed0234a12b099b72 # v2.4.1
        with:
          compose-file: "./docker/docker-compose.yml"

      - name: Execute tests in the running services
        run: |
          docker compose exec test-app pytest

Example Using environment variables

steps:
  - uses: actions/[email protected]
  - uses: hoverkraft-tech/compose-action@3846bcd61da338e9eaaf83e7ed0234a12b099b72 # v2.4.1
    with:
      compose-file: "./docker/docker-compose.yml"
    env:
      CUSTOM_VARIABLE: "test"

Example using services

Perform docker compose up to some given service instead of all of them

steps:
  # need checkout before using compose-action
  - uses: actions/checkout@v3
  - uses: hoverkraft-tech/compose-action@3846bcd61da338e9eaaf83e7ed0234a12b099b72 # v2.4.1
    with:
      compose-file: "./docker/docker-compose.yml"
      services: |
        helloworld2
        helloworld3

Example using up-flags

Specify flags to pass to the docker compose up.

Default is none.

Can be used to pass the --build flag, for example, if you want persistent volumes to be deleted as well during cleanup.

A full list of flags can be found in the Docker compose up documentation.

Example using down-flags

Specify flags to pass to the docker compose down command during cleanup.

Default is none.

Can be used to pass the want persistent volumes to be deleted as well during cleanup.

A full list of flags can be found in the Docker compose down documentation.

Example using compose-flags

Specify flags to pass to the docker compose command. Default is none.

A full list of flags can be found in the Docker compose documentation.

steps:
  # need checkout before using compose-action
  - uses: actions/checkout@v3
  - uses: hoverkraft-tech/compose-action@3846bcd61da338e9eaaf83e7ed0234a12b099b72 # v2.4.1
    with:
      compose-file: "./docker/docker-compose.yml"
      compose-flags: "--profile profile-1"

Specify multiple compose files to use with the docker compose command.

This is useful when you have a base compose file and additional files for different environments or configurations.

steps:
  # need checkout before using compose-action
  - uses: actions/checkout@v3
  - uses: hoverkraft-tech/compose-action@3846bcd61da338e9eaaf83e7ed0234a12b099b72 # v2.4.1
    with:
      compose-file: |
        ./docker/docker-compose.yml
        ./docker/docker-compose.ci.yml

Contributing

Contributions are welcome! Please see the contributing guidelines for more details.

License

This project is licensed under the MIT License.

SPDX-License-Identifier: MIT

Copyright © 2025 hoverkraft

For more details, see the license.

---

This documentation was automatically generated by CI Dokumentor.