.editorconfig

@@ -0,0 +1,10 @@
+# editorconfig.org
+root = true
+
+[*]
+indent_style = space
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+indent_size = 2

.gitattributes

@@ -0,0 +1,11 @@
+# make github collapse diffs for generated files within PRs
+# https://github.com/github/linguist#generated-code
+
+# make github know about vendored code
+# https://github.com/github/linguist#vendored-code
+**/vendor/** linguist-vendored
+
+# OWNERS files are YAML
+OWNERS linguist-language=Yaml
+**/OWNERS linguist-language=Yaml
+OWNERS_ALIASES linguist-language=Yaml

.github/dependabot.yml

@@ -0,0 +1,7 @@
+---
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: daily

.pre-commit-config.yaml

@@ -0,0 +1,71 @@
+---
+# See https://pre-commit.com for more information
+# See https://pre-commit.com/hooks.html for more hooks
+
+# ignore:
+# vendor'd code (that has vendor in its path)
+exclude: vendor
+
+repos:
+  - repo: https://github.com/adrienverge/yamllint
+    rev: v1.25.0
+    hooks:
+      - id: yamllint
+        args:
+          - --format=parsable
+          - --strict
+
+  - repo: https://github.com/jumanjihouse/pre-commit-hook-yamlfmt
+    rev: 0.1.0  # or higher tag
+    hooks:
+      - id: yamlfmt
+        args:
+          - --preserve-quotes
+          - --mapping=2
+          - --sequence=4
+          - --offset=2
+          - --width=1200    # match .yamllint.yaml; we don't care about line-length.
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v3.3.0
+    hooks:
+      - id: check-added-large-files
+      - id: check-byte-order-marker
+      - id: check-case-conflict
+      - id: check-executables-have-shebangs
+      - id: check-json
+      - id: check-merge-conflict
+      - id: check-symlinks
+      - id: detect-private-key
+      - id: end-of-file-fixer
+      - id: forbid-new-submodules
+      - id: mixed-line-ending
+      - id: pretty-format-json
+        args:
+          - --autofix
+      - id: sort-simple-yaml
+      - id: trailing-whitespace
+
+  - repo: https://github.com/syntaqx/git-hooks
+    rev: v0.0.17
+    hooks:
+      - id: forbid-binary
+      # See checks in shellcheck wiki: https://github.com/koalaman/shellcheck/wiki/
+      - id: shellcheck
+      - id: shfmt
+        # do not use these args (yet):
+        # -s, simplify code
+        # -mn, minify to reduce its size
+        args:
+          - -w      # autofix in place
+          - -d      # show diff
+          - -i=2    # indent 2 spaces
+
+  - repo: https://github.com/ansible/ansible-lint
+    rev: v4.3.5
+    hooks:
+      - id: ansible-lint
+        args:
+          # excludes
+          # 106 is deprecated. https://ansible-lint.readthedocs.io/en/latest/default_rules.html#role-name-does-not-match-a-z-a-z0-9-pattern
+          - -x=106

.python-version

@@ -0,0 +1 @@
+3.8.5 ansible-buildkite-agent

.travis.yml

@@ -0,0 +1,15 @@
+---
+before_install:
+  - sudo apt-get -qq update
+  - pip install -r requirements.txt
+before_script:
+  - workflow/pre-build.sh
+cache:
+  directories:
+    - $HOME/.cache/pre-commit
+language: python
+script:
+  - workflow/ci.sh
+services:
+  - docker
+sudo: required

.yamllint.yaml

@@ -0,0 +1,22 @@
+---
+# https://yamllint.readthedocs.io/en/stable/configuration.html#default-configuration
+extends: default
+
+yaml-files:
+  - .toolsharerc
+  - .yamllint.yaml
+  - '*.yaml'
+  - '*.yml'
+  - OWNERS_ALIASES
+  - OWNERS
+
+rules:
+  document-start:
+    level: error
+  indentation: false
+  line-length:
+    max: 1200
+    level: warning
+  quoted-strings:
+    quote-type: single
+    required: only-when-needed

CHANGELOG.md

@@ -7,53 +7,115 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
-...
+* Add: `buildkite_agent_name` option.
+* Fix: Use `brew` executable from `buildkite_agent_brew_dir` when targeting homebrew task.
 
-## 2.1.0 - 2019-08-20
+## 4.2.0
 
-- `buildkite_agent_username` option for configuring the name of the user to run the service as.
-- `buildkite_agent_user_description` option for configuring the description of the user to run the service as.
+* Add: If `buildkite_agent_logs_dir` is unset for the target platform, log to stdout/stderr instead of an arbitrary default file.
 
-## 2.0.0 - 2019-08-11
+## 4.1.0
 
-- require ansible `2.8.x` for `win_user_profile` support.
-- take care of `win_nssm` deprecations within ansible 2.8.x.
+* Add: macOS `buildkite_agent_brew_dir` to set where `brew` is installed.
 
-## 1.2.1 - 2019-04-25
+## 4.0.0
 
-- `buildkite_agent_nssm_exe` option.
-- `buildkite_agent_tags_including_queue` option.
+* Fix: Windows user password handling + doc. This was regressed within `3.3.1` during e1d9460, we're really sorry about that.
 
-## 1.2.0 - 2019-03-16
+## 3.3.1
+
+* Fix: don't accidentally run homebrew with become, it refuses.
+* Fix: correct permissions and ownership on macOS configuration file and environment hook.
+* Add: `buildkite_agent_homebrew_tap_url` (to allow overriding with an ssh-based tap for reliability).
+
+## 3.3.0
+
+* Fix: don't update homebrew on macOS as part of installing, since this is potentially very slow.
+* Add: make installing the binary be optional (`buildkite_agent_should_install_binary`), in case people (yes, improbable) elect to install it differently.
+
+## 3.2.1
+
+* Fix: all platforms will run `buildkite_agent_count` job-runners now, defaulting to `1`.
+* Fix: macOS `buildkite_agent_executable` is correct for the homebrew install now.
+* Fix: Debian - user is now explicitly placed into the user's group.
+
+## 3.2.0
+
+* Added: ability to create user (on Debian) with a specific UID.
+
+## 3.1.1
+
+* Fixed: systemd path to buildkite agent logs; needs to be a file, not a directory.
+
+## 3.1.0
+
+Add support for shims/scripts wrapping the `buildkite-agent` binary, instead of directly calling the binary.
+This can be useful, for example, if you need to fetch your agent registration token from a secret store before running `buildkite-agent`.
+
+If not using a shim/script, no changes are needed.
+To use a shim instead of directly calling the `buildkite-agent` binary, point `buildkite_agent_executable`
+to your shim, and `buildkite_agent_start_command` to your shim's args.
+
+* Added `buildkite_agent_executable` option.
+* Added `buildkite_agent_start_command` option.
+
+## 3.0.0
+
+Version bump for breaking change. This is the same as 2.2.1 with corrected meta/main.yml.
+
+## 2.2.1
+
+* fixes to ansible 2.9.0 updates.
+
+## 2.2.0
+
+* porting to support ansible 2.9.0.
+
+## 2.1.0
+
+* `buildkite_agent_username` option for configuring the name of the user to run the service as.
+* `buildkite_agent_user_description` option for configuring the description of the user to run the service as.
+
+## 2.0.0
+
+* require ansible `2.8.x` for `win_user_profile` support.
+* take care of `win_nssm` deprecations within ansible 2.8.x.
+
+## 1.2.1
+
+* `buildkite_agent_nssm_exe` option.
+* `buildkite_agent_tags_including_queue` option.
+
+## 1.2.0
 
 ### Added
 
-- `buildkite_agent_allow_service_startup` option.
-- `buildkite_agent_expose_secrets` option.
-- `buildkite_agent_tags_from_gcp_labels` option.
-- `buildkite_agent_start_parameters` option for Debian and Windows.
-- Debian `buildkite_agent_systemd_override_template` option.
-  - Related - stop using systemd _template_ unit file (because `buildkite_agent_start_parameters` and v3.6.0+ allow `--spawn` for multiple job-runners).
+* `buildkite_agent_allow_service_startup` option.
+* `buildkite_agent_expose_secrets` option.
+* `buildkite_agent_tags_from_gcp_labels` option.
+* `buildkite_agent_start_parameters` option for Debian and Windows.
+* Debian `buildkite_agent_systemd_override_template` option.
+  * Related - stop using systemd _template_ unit file (because `buildkite_agent_start_parameters` and v3.6.0+ allow `--spawn` for multiple job-runners).
 
-## 1.1.0 - 2018-12-11
+## 1.1.0
 
 ### Added
 
-- macOS support - #7
-- Windows support - #6
+* macOS support - #7
+* Windows support - #6
 
-## 1.0.0 - 2018-04-18
+## 1.0.0
 
 ### Added
 
-- Support for Buildkite Agent v3.
-- Support for Ubuntu 16.04.
+* Support for Buildkite Agent v3.
+* Support for Ubuntu 16.04.
 
 ### Removed
 
-- Remove support for Ubuntu 14.04.
-- Remove support for Buildkite Agent v2.
+* Remove support for Ubuntu 14.04.
+* Remove support for Buildkite Agent v2.
 
 ## 0.1.0
 
-- Initial release.
+* Initial release.

OWNERS

@@ -0,0 +1,4 @@
+---
+approvers:
+  - team-eng-velocity
+  - team-reliability-engineering

OWNERS_ALIASES

@@ -0,0 +1,17 @@
+---
+# Please keep lists alphabetically, case-insensitive, sorted
+
+# These are lists of github usernames.
+# Yes, there's a special hell for us and we don't have a mapping system for GH->improbable and back, yet.
+aliases:
+  team-eng-velocity:
+    - DoomGerbil         # Sean Robertson
+    - filipVisko         # Filip Viskovic
+    - Helcaraxan         # Duco van Amstel
+    - PaulSonOfLars      # PaulSonOfLars
+
+  team-reliability-engineering:
+    - Christopher-Steel  # Christopher Steel
+    - filipVisko         # Filip Viskovic
+    - LeadTimeNull       # Andreas Valentin Pederson
+    - PaulSonOfLars      # PaulSonOfLars

README.md

@@ -10,15 +10,21 @@ An Ansible role to install the [Buildkite Agent](https://buildkite.com/docs/agen
 - `buildkite_agent_conf_dir` - Buildkite Agent configuration directory (default: `/etc/buildkite-agent`)
 - `buildkite_agent_count` - Number of agents [if you want to run multiple per host](https://buildkite.com/docs/agent/v3/ubuntu#running-multiple-agents).
 - `buildkite_agent_debug` - Flag to enable Buildkite Agent debugging.
-- `buildkite_agent_start_parameters` - supply parameters for the `buildkite start` command.
+- `buildkite_agent_executable` - The location of the buildkite-agent executable, or a shim/wrapper you wish to use.  Defaults to the default platform-specifc installation location.
+- `buildkite_agent_should_install_binary[ansible_os_family]` - When `yes`, use the platform-specific installation method to install the binary. When `no`, don't. Useful if you prefer to install the binary via other means.
+- `buildkite_agent_start_parameters` - Command line flags to pass to the `buildkite-agent start` command to start the agent.
+- `buildkite_agent_start_command` - Arguments passed verbatim to the `buildkite_agent_executable` at startup.  Wraps `buildkite_agent_start_parameters` by default - if using a shim or script for `buildkite_agent_executable`, override this instead of `buildkite_agent_start_parameters`.
 - `buildkite_agent_token` - Buildkite agent registration token. Available from `https://buildkite.com/organizations/{org-slug}/agents`.
+- `buildkite_agent_name` - Name for the Buildkite agent(s).
 
 ### Paths-related
 
 - `buildkite_agent_builds_dir` - Path to where agent will perform builds.
   - Note: on Windows, this defaults to `c:/b` because long filenames still cause problems in the 21st Century.
 - `buildkite_agent_hooks_dir` - Path to where agent will look for hooks.
 - `buildkite_agent_plugins_dir` - Path to where agent will look for plugins.
+- `buildkite_agent_logs_dir` - Path to write agent logs - if unset, logs are printed to stdout/stderr.
+  - Note that this option only applies to Windows, and Linux platforms with [systemd versions newer than late 2017](https://github.com/systemd/systemd/issues/3991).
 
 ### Configuration settings
 
@@ -42,6 +48,9 @@ Variable names below map to [the agent configuration documentation](https://buil
 - `buildkite_agent_tags` - List of tags for agent; Don't use this to set `queue`, as that is handled via `buildkite_agent_queue` (default: `[]`)
 - `buildkite_agent_tags_including_queue` - List of tags for the agent that include `queue`. (default: `queue={{ buildkite_agent_queue}},{{ buildkite_agent_tags }}`)
 - `buildkite_agent_username` - the username to run the `buildkite-agent` process/service as.
+- `buildkite_agent_user_uid` - the user ID to make the user be, if specified.
+  - this is ignored on Windows.
+  - This is useful because it allows the UID to be well-known, which in turn allows people to build dockers which contain a work-user with this same UID, allowing them to avoid the otherwise-usual-problems where files are written into a host-mounted volume and the UIDs mismatch, bricking the host's filesystem for future builds.
 - `buildkite_agent_user_description` - the description of the user to run the `buildkite-agent` process/service as.
 
 ### Platform specific settings
@@ -62,7 +71,9 @@ Variable names below map to [the agent configuration documentation](https://buil
 
 #### Darwin
 
+- `buildkite_agent_homebrew_tap_url` - You could use `git@github.com:buildkite/homebrew-buildkite.git` if you clone over ssh because you find that more reliable, but your ansible connection needs an ssh key to authenticate to github then (forwarding your ssh-agent works fine). Omitted otherwise.
 - `buildkite_agent_load_bash_profile` - Load `$HOME/.bash_profile` with buildkite agent environment hook. Ensures agent will load with bash environment.
+- `buildkite_agent_brew_dir` - Specify where `brew` is installed, `brew` uses different defaults for Intel vs. ARM processors.
 
 ### Debugging
 
@@ -72,4 +83,13 @@ Variable names below map to [the agent configuration documentation](https://buil
 
 See the [examples](./examples/) directory.
 
+## Local workflow
+
+```bash
+# Get set up - one time. Read it first.
+workflow/onboarding.sh
+# Run what CI would.
+workflow/ci.sh
+```
+
 [NSSM]: https://nssm.cc