Skip to content

Latest commit

 

History

History
125 lines (101 loc) · 14.9 KB

README.md

File metadata and controls

125 lines (101 loc) · 14.9 KB
Raw

Automator

Description

automator.sh is a bash script used to automate cross-repository workloads. It clones an user-defined list of GitHub repositories, runs a series of user-defined commands in each of those repositories, then forks, commits, and pull requests any changes back to the upstream repository. It can be executed either as a standalone script or in Prow CI as a presubmit, postsubmit, or peridoic job.

Prerequisites

  1. Bash 4.0+ interpreter.

  2. The following third-party tools must be available in the execution environment:

  3. For MacOS, additionally install the coreutils and gnu-getopt Homebrew packages, then follow the postinstall instructions to add the commands to your PATH:

    brew install gnu-getopt coreutils

  4. Unless executed in dry-run mode (i.e. --dry-run), it requires the use of a GitHub access token to identify the user and interact with the GitHub API.

Usage

automator.sh [options]...

Options

The following is a list of supported options for automator.sh. If an option is optional, then its default value will be used. If an option is required and unspecified, then execution will fail with a non-zero exit code.

Option Argument Description Example(s)
--branch string The branch of the repository to clone and base the pull request. This option is optional and will default to the currently checked out branch if inside a git directory. master
--org string The organization of the repository to clone and base the pull request. This option is required. istio
--repo string,... The repository(ies) to clone and base the pull request. More than one repository can be specified via a comma-separated string. This option is required. common-files(single repo)
istio,istio.io,api,test-infra(multiple repos)
--title template This option is optional and will default to the following template: Automator: update $AUTOMATOR_ORG/$AUTOMATOR_REPO@$AUTOMATOR_BRANCH-$AUTOMATOR_MODIFIER. Update istio/api
--match-title template Reuse an existing pull request matching this title. Rather than create a new pull request, the existing pull request will be updated with any new changes. This option is optional and will default to the value of the --title template. Update istio/api
--body template The body of the pull request. This option is optional and will default to the following template: Generated by Automator - $(date -uIseconds). Generated by Automator - $(date -uIseconds)
--labels string,... The label(s) to add to the pull request. More than one label can be specified via a comma-separated string. This option is optional. auto-merge(single label)
auto-merge,new,env/aws(multiple labels)
--user string The user name associated with the commit, fork, and pull request. This option is optional and will default to the login of the github token. clarketm
--email string The email address associated with the commit, fork, and pull request. This option is optional and will default to the email of the github token. [email protected]
--modifier string A segment of text to append to the branch name of the fork for additional context. This option is optional and will default to automator.sh. update-api-dependency
--token-path file Path to a file containing a GitHub access token. The token is used to identify the user and interact with the GitHub API. This option is required if --token is not specified. /path/to/github/token
--token string A GitHub access token. The token is used to identify the user and interact with the GitHub API. This option is required if --token-path is not specified. aSuperSecretGithubToken
--token-env Like --token, but read from GH_TOKEN instead. aSuperSecretGithubToken
--script-path script Path to a bash script containing the command(s) to execute in each cloned repository. This option is required if --cmd is not specified. /path/to/bash/script
--cmd command A command to execute in each cloned repository. This option is required if --script-path is not specified. go get istio.io/istio(single command)
go get istio.io/api && make gen(multiple commands)
--verbose Enable verbose output. Print commands and their arguments as they are executed. WARNING: this has the potential to print sensitive data to standard output.
--strict Enable strict mode. When enabled, if the command does not produce a git diff it will exit with a non-zero exit code.
--dry-run Enable dry run mode. When enabled, the command will terminate early and NOT perform a commit, push, or pull request for any changes. This is useful for local testing/debugging or when concerned only with the git diff or exit code of the command.
--git-exclude string Applied to list of file changes in the commit CAUSING this automator run using grep -vE '<string>'. If no additional changes remain, the automator task will stop. ^common/
^pkg/|^pilot/

Environment Variables

The following is a list of environment variables supported by automator.sh. These variables can be specified in any of the template options above (e.g. --title) or in the command (e.g. --cmd) or script (e.g. --script-path) executed by automator.sh.

Variable Description Example(s)
AUTOMATOR_ORG Contains the value of the GitHub organization. It is set via the --org option. istio
AUTOMATOR_REPO Contains the current value of the repository. It is set via the --repo option. If more that one repository is specified, this variable will contain the repository currently being processed. istio.io
AUTOMATOR_BRANCH Contains the value of the branch. It is set via the --branch option. master
AUTOMATOR_MODIFIER Contains the value of the modifier. It is set via the --modifier option. update-deps
AUTOMATOR_ROOT_DIR The absolute path of the current working directory. /path/of/current/working/dir
AUTOMATOR_REPO_DIR The absolute path of the directory of the cloned repository. If more that one repository is specified, this variable will contain the path to the repository currently being processed. /path/of/cloned/repo/dir
AUTOMATOR_SRC_ORG Set to the value of Prow's REPO_OWNER. istio
AUTOMATOR_SRC_REPO Set to the value of Prow's REPO_NAME. test-infra
AUTOMATOR_SRC_BRANCH Set to the value of Prow's PULL_BASE_REF. master
AUTOMATOR_SHA Set to the git commit sha (if inside a git directory). c6418d1439d12eab2f1a4eae89f6eee46a34c31b
AUTOMATOR_SHA_SHORT Set to the git commit sha trimmed to 8 character (if inside a git directory). c6418d14
AUTOMATOR_SHA_COMMIT_DATE Set to the git sha committed date. 2020-09-24

Examples

Testing / Debugging

To test or debug automator.sh locally, first ensure the execution environment meets the above prerequisites. Additionally, supply the --dry-run option. This will prevent all GitHub state modifications (i.e. fork, commit, and pull request). Instead, it will print a git diff to standard out if any files were changed, then exit.

/path/to/automator.sh \
--org=istio \
--repo=test-infra \
--branch=master \
--title='my automator test' \
--cmd="echo 'do something fun' > file.txt" \
--dry-run
--- /dev/null
+++ b/file.txt
@@ -0,0 +1 @@
+do something fun