[Docs]: Examples for docker usage

[ToshY]

Describe the documentation issue

The current documentation regarding the Docker section is missing how to use it. I want to try and run the docker image locally, but I am not being able to figure it out from checking the docker-compose.yml / Makefile, as it does not really show usages.

This was as far as I currently got:

$ docker run -it -v $(pwd):/app --workdir /app --env TARGET_GH_TOKEN=$(gh auth token) --env SOURCE_GH_TOKEN=$(gh auth token) --env SOURCE_REPO_PATH=<owner/template> --env UPSTREAM_BRANCH=main --env GITHUB_SERVER_URL=https://github.com --rm andyaugustin/actions-template-sync:v2.5.2

::group::git init
::info::set git global configuration
fatal: not in a git directory

$(pwd) in above docker command denotes the following host directory structure.

~/my/project/
├── .git
└── src

Not sure how/what I need to mount. Could you please elaborate?

Links

• https://andreasaugustin.github.io/actions-template-sync/DOCKER/
• document how to use the docker images #254

Acknowledgements

• I may be able to submit a pull-request to fix this issue.

[ToshY]

@AndreasAugustin Could you supply some examples here on how-to-use the docker image?

[ToshY]

🦗

Is this repo still maintained?

[AndreasAugustin]

Hi @ToshY repository is stil maintained but need to admit not super actively.
This issue is most likely a duplicate of #254
Seems the docker image is not widely used but I will try to find some time to add some docs 👍

[ToshY]

Hey @AndreasAugustin 👋

That would be much appreciated, as I want to try and use this as it seems to be a more robust solution than other "template sync" alternatives (like coopTilleuls/template-sync), so having a couple basic docker examples would be nice 👍

[AndreasAugustin]

Hey @AndreasAugustin 👋

That would be much appreciated, as I want to try and use this as it seems to be a more robust solution than other "template sync" alternatives (like coopTilleuls/template-sync), so having a couple basic docker examples would be nice 👍

Nice. Can you possibly give some more details how you want to use it? Always interested in some use cases.

[AndreasAugustin]

@ToshY I think it is actually a bug.
To solve it inside the container

git config --global --add safe.directory /app/

solves at least part of the issue (possibly all).

You can try it with:

services:
  dev:
    image: andyaugustin/actions-template-sync:v2.5.2
    entrypoint: ["/bin/bash"]
    working_dir: /app/
    tty: true
    volumes:
      - .:/app/
    environment:
      - TARGET_GH_TOKEN="foo"
      - SOURCE_GH_TOKEN="bar"
      - SOURCE_REPO_PATH="foo"
      - GITHUB-SERVER_URL="https://github.com"
      - GIT_USER_NAME="abc"
      - GIT_USER_EMAIL="a@foo.com"

docker compose run dev

Will need some further research and debugging but possibly this part already helps a bit.

[ToshY]

@ToshY I think it is actually a bug. To solve it inside the container

git config --global --add safe.directory /app/
solves at least part of the issue (possibly all).

You can try it with:

services:
dev:
image: andyaugustin/actions-template-sync:v2.5.2
entrypoint: ["/bin/bash"]
working_dir: /app/
tty: true
volumes:
- .:/app/
environment:
- TARGET_GH_TOKEN="foo"
- SOURCE_GH_TOKEN="bar"
- SOURCE_REPO_PATH="foo"
- GITHUB-SERVER_URL="https://github.com"
- GIT_USER_NAME="abc"
- GIT_USER_EMAIL="a@foo.com"
docker compose run dev
Will need some further research and debugging but possibly this part already helps a bit.

@AndreasAugustin This helped very much. I ended up with a trail-and-error approach (with chatgpt) and eventually got it working. In the process, also encountered a bug, for which I will create a PR.

The following command succesfully created a PR in one of the derived template repositories.

[ -f .git/hooks/commit-msg ] && mv .git/hooks/commit-msg .git/hooks/commit-msg.disabled; \
[ -f .git/hooks/pre-commit ] && mv .git/hooks/pre-commit .git/hooks/pre-commit.disabled; \
docker run -it \
  -v $(pwd):/app \
  --workdir /app \
  --rm \
  --env TARGET_GH_TOKEN="$(gh auth token)" \
  --env SOURCE_GH_TOKEN="$(gh auth token)" \
  --env SOURCE_REPO_PATH="<owner/template>" \
  --env GITHUB_SERVER_URL="https://github.com" \
  --env HOSTNAME="github.com" \
  --env SSH_PRIVATE_KEY_SRC="$(cat ~/.ssh/id_ed25519)" \
  --env UPSTREAM_BRANCH=main \
  --env TEMPLATE_SYNC_IGNORE_FILE_PATH=".templatesyncignore" \
  --env IS_FORCE_PUSH_PR=true \
  --env PR_COMMIT_MSG="chore: sync template" \
  --env PR_TITLE="[chore] upstream merge template repository" \
  --env GIT_USER_NAME="ToshY" \
  --env GIT_USER_EMAIL="<redacted>" \
  --entrypoint "/bin/bash" \
  andyaugustin/actions-template-sync:v2.5.2 \
  -c "sed -i 's/retun 0/return 0/' /bin/sync_template.sh && git config --global --add safe.directory /app && /bin/entrypoint.sh"; \
[ -f .git/hooks/commit-msg.disabled ] && mv .git/hooks/commit-msg.disabled .git/hooks/commit-msg; \
[ -f .git/hooks/pre-commit.disabled ] && mv .git/hooks/pre-commit.disabled .git/hooks/pre-commit

Some notes regarding running the command above:

• The temporary moving/disabling of the .git/hooks is required in my case, as my hooks contain docker command. Please consider adding another env variable, e.g. COMMIT_ARGS, so could be used to pass -n here:

  actions-template-sync/src/sync_template.sh

  Line 502 in 4fdac2b

  git commit --signoff -m "${PR_COMMIT_MSG}"

• The env HOSTNAME is required (and set to github.com), else it will try to use an docker container hostname which leads to error validating token: Get "https://92828dec57e7/api/v3/": dial tcp 172.18.0.3:443: connect: connection refused
• The env TEMPLATE_SYNC_IGNORE_FILE_PATH is required, else it will give the error Missing env variable 'TEMPLATE_SYNC_IGNORE_FILE_PATH'. The file doesnt need to exist on the host though.
• The env SSH_PRIVATE_KEY_SRC is required if you use SSH for your remote instead of HTTPS (see the .git/config to verify)
• The env PRE_COMMIT_MSG is required, else it will give the error Missing env variable 'PR_COMMIT_MSG'
• The env PR_TITLE is required, else it will have pushed the branch but not created a PR, and show warning pull request title must not be blank; ::warn::Creating the PR failed.
• The sed -i 's/retun 0/return 0/' /bin/sync_template.sh is a temporary fix for which another PR must be made, as it has retun instead of return:

  actions-template-sync/src/sync_template.sh

  Lines 299 to 300 in 4fdac2b

  	info "'pr_labels' is empty. Skipping labels check"
  	retun 0

  • Created PR Fix sync_template.sh return command #661

Some additional observations:

• After it succesfully executed, I noticed that the branch was still checked out locally (_0e51840).
  • One issue is that files were written as root. This makes sense because I did not pass the user to the docker command. However if I do pass -u $(id -u):$(id -g) to the docker command it immediatly fails and leads to error error: could not lock config file //.gitconfig: Permission denied. Is there a way to resolve the permissions issues? I'd rather run this as the current user, and not root, to prevent these file owner permissions issues.
  • Is it also possible that after the script created the PR, to automatically check out the base branch (main) again?