From 0c61c4447c02525bd75f580fe06417ab6f906ac9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Harald=20Nordg=C3=A5rd-Hansen?= Date: Sun, 30 May 2021 12:55:35 +0200 Subject: [PATCH] Update README.md wth better docs. --- README.md | 65 ++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 64 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 7d98973..4f37265 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,10 @@ The behaviour is inspired by CodeFresh docker steps, the idea is to act similar to the script-executor task, but instead of running on the agent, the script is run inside an arbitrary container. +There is also support for spinning up companion containers, typically for +test databases etc. Those "services" are assumed to be completely configured +using environment variables. + ## What to expect This is built and tested for running inside the gocd-agent-dind docker image, @@ -17,7 +21,66 @@ Service images are given the environment, and nothing else. ## Usage -TODO: Add yaml sample. +The mandatory configuration is the image to run, and the commands to +run in it. Commands are run in bash, with 'set -ex' applied. I.e. it will bail +out on errors, and you can see in the task log what you did. + +Optional configuration is "pull", that can be set to false in order to not +try to pull images. This allows the task to work with images that have not +been pushed to a registry. Remember that turning off pull applies to all +images, also services. + +A simple task to build a node application could be something like: +```yaml +tasks: + - plugin: + configuration: + id: docker-step + version: 0.1.0 + options: + image: node:16 + commands: | + yarn + yarn build + yarn test +``` + +The pipeline working directory is mounted on `/working`, which is also the +working directory when the commands start. The container runs as the same +user as the agent, to avoid making a mess of file permissions etc. + +When running more complex tests, e.g. testing a Django build, services are +needed. A service does not get any filesystem mounted, nor is the user +changed. But everything is run in a separate network so things are reachable +using the service name given. If multiple services are needed, just supply +them one on a line, the format is `;`: + +```yaml +jobs: + build-and-test-django: + environment_variables: + POSTGRES_DB: test + POSTGRES_USER: test + POSTGRES_PASSWORD: test + DB_HOST: pg + tasks: + - script: | + set -e + docker build -t django-app:test . + docker pull postgres:latest + - plugin: + configuration: + id: docker-step + version: 0.1.0 + options: + image: django-app:test + pull: 'false' + commands: | + cd /app + ./manage.py test + services: | + pg;postgres:latest +``` ## Credits