@@ -66,3 +66,26 @@ To keep `.tool-versions` in sync with `.gitlab-ci.yml`, there is a helper script
1. Run `./scripts/update-asdf-version-variables` to update a refresh of the `.gitlab-ci-asdf-versions.yml` file
1. Commit the changes
1. A CI job (see [`asdf-tool-versions.md`](../asdf-tool-versions.md)) will validate the changes.
# Diagnosing `asdf` setup issues
## `asdf` plugins don't return versions as expected
In order to avoid dependencies, many `asdf` plugins rely on basic unix text utilities like `sed` and `awk` to parse JSON. Many rely on the fact that responses from the GitHub API are pretty-printed JSON, not compressed JSON. However, the GitHub API will only pretty-print JSON when it detects the user-agent as being `curl`. For other user-agents, the response will be compressed for efficiency.
Ensure that you haven't overridden your `curl` user-agent on your workstation.
Check your `.curlrc` for the `user-agent` setting. Additionally, running `curl https://api.github.com/orgs/gitlabhq` should return pretty-printed JSON. If it is compressed, `asdf` plugins may not work as expected.
## Plugins require other asdf tools
If you find that a plugin is failing to install, it sometimes helps to setup a global default. Care has been taken to avoid this situation, but if you're stuck, give it a try:
```shell
# If a plugin is complaining that it cannot compile because golang hasn't been configured...
# set the global version of golang the same as the current version
asdf global golang $(asdf current golang|awk '{ print $2 }')
asdf install
```
If this happens, please open an issue in the appropriate tracker, so that a better long-term solution can be applied.
