---
tags:
  - GIT
  - CI/CD
  - CI-CD
---
To test and validate your `docker-compose` infrastructure configurations right inside your homelab, you can use Gitea Actions to automatically check your YAML syntax and test your container builds every time you make an edit. [[1](https://mortylen.hashnode.dev/gitea-self-hosted-workflow-action-for-ci), [2](https://ramnode.com/guides/series/gitea-devops/gitea-setup)]

Here is how to set up an automated testing pipeline specifically for a homelab Docker Compose repository.

🛠️ Step 1: Set Up the Workflow Directory

In your homelab Git repository containing your `docker-compose.yml` files, create the specific workflow path: [[1](https://www.stackhero.io/en-CA/services/Docker/documentations/Deploy-with-GitHub-Actions)]

- **File path:** `.gitea/workflows/docker-test.yaml`

📝 Step 2: Paste the Homelab Validation Template

Copy and paste this template into your new file. It is optimized to perform two critical steps: lint your YAML formatting for typos, and dry-run your Docker Compose setup to ensure your container configurations are valid. [[1](https://www.reddit.com/r/docker/comments/1i32i3z/one_large_compose_file/), [2](https://www.docker.com/blog/compose-to-kubernetes-to-cloud-kanvas/)]

`name: Docker Compose Validator`
`run-name: Homelab configuration test by ${{ gitea.actor }} 🛠️`

`on:`
  `push:`
    `branches: [ "main", "master" ]`
  `pull_request:`
    `branches: [ "main", "master" ]`

`jobs:`
  `validate-and-test:`
    `runs-on: ubuntu-latest`
    
    `steps:`
      `# 1. Pull down your homelab repository code`
      `- name: Checkout Repository Code`
        `uses: actions/checkout@v4`

      `# 2. Check all YAML files for syntax, indentation, and formatting errors`
      `- name: Lint YAML Syntax`
        `uses: https://github.com`
        `with:`
          `file_or_dir: "."`

      `# 3. Verify that the docker-compose syntax is structurally sound`
      `- name: Verify Compose File Validity`
        `run: |`
          `echo "Checking docker-compose configuration..."`
          `docker compose config`

      `# 4. Dry-run the build sequence to ensure images and contexts are reachable`
      `- name: Test Build Sequence`
        `run: |`
          `echo "Simulating container build sequence..."`
          `docker compose build`

🔍 Breaking Down How This Works for Homelabbers

- **YAML Linting:** Homelab configurations frequently break due to an accidental extra space or missing indentation. The `action-yamllint` step scans your files and alerts you to formatting errors before they hit your live system.
- **`docker compose config`:** This command acts as a built-in validator. It reads your `docker-compose.yml` file, processes any variables, and outputs an error if you have typos in your keys, volume definitions, or network syntax. [[1](https://labex.io/tutorials/docker-how-to-use-docker-compose-config-command-to-validate-and-view-compose-files-555074), [2](https://www.reddit.com/r/docker/comments/13vupxt/switching_from_portainer_to_dockercompose_and/), [3](https://medium.com/@adriansyah1230/mastering-docker-compose-a-practical-guide-to-multi-container-applications-c76811010131)]
- **`docker compose build`:** If your compose files use the `build:` block to compile local Dockerfiles instead of just pulling pre-made images, this step ensures your Dockerfiles successfully build without crashing.

⚠️ Crucial Homelab Gotchas to Keep in Mind

1. **Environment Variables (`.env`):** If your `docker-compose.yml` relies on an external `.env` file containing local paths, secret tokens, or personal domain names, `docker compose config` will fail in Gitea Actions because that file is missing. You should either add a `.env.example` file to your Git repository and rename it during the workflow run, or map those variables into **Gitea Secrets**.
2. **Local Volume Paths:** If your compose files map to absolute local storage paths (e.g., `/mnt/user/appdata/nginx`), the Gitea Act Runner environment won't have access to those actual directories. For testing purposes, it is safest to use relative paths (e.g., `./nginx/config`) or let Docker generate named volumes during the validation phase.
3. **Runner Capabilities:** Ensure that your local `act_runner` setup has access to a Docker daemon. If you installed your runner using Docker-in-Docker (DinD), it will easily execute the `docker compose` commands embedded in this workflow. [[1](https://versich.com/blog/a-practical-guide-to-building-docker-image-in-gitlab/)]