tcwlab/dgoss repository overview

⁠tcwlab/dgoss

⁠Quick start

docker pull tcwlab/dgoss:latest

# Run goss against the current directory's goss.yaml on a target image
docker run --rm \
  -v "$PWD/goss/goss.yaml:/tmp/goss.yaml:ro" \
  -v /var/run/docker.sock:/var/run/docker.sock \
  tcwlab/dgoss:latest \
  dgoss run my-target-image:test

Or as a Forgejo / GitHub Actions container job:

smoketest:
  runs-on: ubuntu-22.04
  container:
    image: tcwlab/dgoss:latest
  env:
    DOCKER_HOST: tcp://docker-in-docker:2375
  steps:
    - uses: https://data.forgejo.org/actions/checkout@v4
    - run: dgoss run my-target-image:test

⁠Recommended consumption

Most tcwlab consumers don't invoke tcwlab/dgoss directly — they call the image-smoketest⁠ composite action from the tcwlab/actions⁠ repo, which wraps this image with a stable input contract (image reference, goss file path, expected version).

- name: Smoke-test built image
  uses: https://<your-forgejo-host>/tcwlab/actions/.forgejo/actions/image-smoketest@v1
  with:
    image: tcwlab/forgejo-build:myservice-${{ github.sha }}
    gossfile: goss/goss.yaml
    expected-version: "1.11.6"

⁠Tags

Always pin a concrete version in production. The image tag mirrors the upstream goss release exactly: tcwlab/dgoss:0.4.9 contains goss v0.4.9 and the matching dgoss wrapper.

⁠Supported architectures

• linux/amd64
• linux/arm64

Every tag is a multi-arch manifest list.

⁠What's included

Base image: docker:29-cli-alpine3.23. Default workdir: /workspace. Default user: gossusr (non-root).

⁠Usage

⁠Validate an image against a goss.yaml

docker run --rm \
  -v "$PWD/goss/goss.yaml:/tmp/goss.yaml:ro" \
  -e DOCKER_HOST=tcp://docker-in-docker:2375 \
  tcwlab/dgoss:0.4.9 \
  bash -c 'GOSS_FILE=/tmp/goss.yaml dgoss run my-target-image:test'

⁠Quick goss --version (no Docker daemon needed)

docker run --rm tcwlab/dgoss:0.4.9 goss --version

⁠Forgejo workflow — full snippet

smoketest:
  name: Image smoketest
  runs-on: ubuntu-22.04
  needs: build-test
  container:
    image: tcwlab/dgoss:0.4.9
  env:
    DOCKER_HOST: tcp://docker-in-docker:2375
  steps:
    - uses: https://data.forgejo.org/actions/checkout@v4
    - name: Pull staging image
      run: docker pull "tcwlab/forgejo-build:myservice-${{ github.sha }}"
    - name: dgoss validate
      env:
        GOSS_FILE: goss/goss.yaml
      run: dgoss run "tcwlab/forgejo-build:myservice-${{ github.sha }}"

⁠Configuration

⁠Environment variables

The image passes goss/dgoss environment variables straight through. Common ones:

⁠Volume mount points

⁠Why tcwlab/dgoss and not the upstream goss binary?

Three reasons:

1. Pinning discipline — public goss release URLs and Docker images use latest or floating majors, which lets a CI tool silently advance. tcwlab/dgoss pins to an exact upstream version and bumps via PR.
2. Consistent footprint — same Alpine 3.23 base, same hardening (non-root user, multi-arch), same OCI labels as every other tcwlab/* image.
3. Composable contract — pairs with the image-smoketest⁠ composite action so consumer repos write a goss.yaml and one uses: line, not 30 lines of Docker plumbing.

⁠Source, issues, contributing

• Source: github.com/tcwlab/dgoss⁠
• Issues / feature requests: github.com/tcwlab/dgoss/issues⁠
• Docker Hub: hub.docker.com/r/tcwlab/dgoss⁠

⁠Build, supply chain

Every release is built and published by the repo's own .forgejo/workflows/ci.yml⁠ on a Forgejo runner:

• Multi-arch build (linux/amd64, linux/arm64) via docker buildx with --sbom=true --provenance=mode=max.
• Self-validation via goss validate against the very goss.yaml shipped in this repo (dogfooding).
• Trivy vulnerability scan on HIGH/CRITICAL severity (failures show up as PR comments).
• Self-lint via betterlint running against the Dockerfile.

The dgoss image version is cut by semantic-release from Conventional Commits on main. The version exactly mirrors the upstream goss release (e.g., release of goss 0.4.11 triggers a new tcwlab/dgoss:0.4.11 image).

⁠License

Apache License 2.0. See LICENSE⁠ for the full text.

goss itself is licensed under Apache-2.0. See goss-org/goss⁠ for details.