Included Tasks

NOTE: This section is incomplete!

Gopherbot ships with a selection of available pipeline tasks, listed here alphabetically. Note that the given examples use bash syntax for simplicity; for ruby and python see the chapter on the Gopherbot API.

email-log - privileged

Usage:

  • FinalTask email-log joe@example.com emily@example.com frank bob
  • FinalTask email-log

Normally used in the fail and final pipelines, emails a copy of the pipeline log. Can also be used with AddTask in the main pipeline, but content will be incomplete.

Notes on the current implementation:
The email function call takes a byte slice for the email body, rather than an io.Reader, meaning the entire body of the message is read in to memory. To limit memory use, Gopherbot allocates a 10MB line-based circular buffer, with maximum 16KB-long lines (terminated by \n), and reads the log to that buffer for emailing. Logs that are longer than 10MB will only send the last 10MB of the log, and lines longer than 16KB will be truncated.

pause-brain - privileged

Usage: AddTask pause-brain

Pause brain operations for backups and restores. After half a minute, the brain automatically resumes; best practice is to add resume-brain after the backup/restore task.

pause-brain

Usage: AddTask pause <seconds>

Causes the pipeline to pause for a number of seconds before proceeding to the next task. Useful when triggering an external process that there's no easy way to poll for completion.

restart-robot - privileged

Usage: AddTask restart-robot

Allow a privileged pipeline to queue a restart of the robot after the pipeline completes. Heavily used by bootstrap and setup plugins. NOTE: This behavior means that tasks added after restart-robot are actually completed before the restart. In practice, the current pipeline will change the state of the robot, and after restarting a plugin init function will check for the state change (e.g. presence of .restore file) and start a new pipeline.

resume-brain - privileged

Usage: AddTask resume-brain

Resume brain functions after backup/restore.

robot-quit - privileged

Usage: AddTask robot-quit

Special purpose task; once called, the robot will exit as soon as all pipelines have completed, and not allow new pipelines to start.

rotate-log - privileged

Usage: AddTask rotate-log <extension>

Useful for e.g. nightly log rotation jobs, when the robot has been started with e.g.: gopherbot -d -l robot.log. For example:

AddTask rotate-log "log.$(date +%a)"

This would keep daily logs of the form robot.log.Mon, etc.

send-message

Usage: AddTask send-message <str> (...)

Have the robot send a message in the channel, normally to report status of a build. Can be a single long string, or multiple strings; in the case of multiple strings they will be joined with a space separator.

ssh-agent - privileged

Usage:

  • AddTask ssh-agent start <path/to/key> <timeout> - requires BOT_SSH_PHRASE in parameters
  • AddTask ssh-agent stop - uses _SSH_AGENT_HANDLE, automatically added as FinalTask by start, deploy
  • AddTask ssh-agent deploy <timeout> - requires GOPHER_DEPLOY_KEY in parameters

The ssh-agent task uses Go ssh-agent libraries to start a new Goroutine loaded with a deployment key, or regular encrypted key. The start and deploy sub-commands automatically add a FinalTask ssh-agent stop to the pipeline to ensure cleanup. This task can be used with ssh-git-helper and git-command to work with git repositories.

The start and deploy sub-commands also create a socket in $GOPHER_HOME and sets the SSH_AUTH_SOCK parameter in the pipeline, so e.g. a "bash" task could use native ssh commands.

See also:

  • plugins/samples/bootstrap.py - previous bootstrapping pipeline

ssh-git-helper - privileged

Usage:

  • AddTask ssh-git-helper addhostkeys <encoded-host-keys> - create a known_hosts file from the encoded keys
  • AddTask ssh-git-helper scan <host> - fallback sub-command to scan a remote host for the host keys
  • AddTask ssh-git-helper loadhostkeys <repo uri> - for github, bitbucket, retrieve host keys from a known https API endpoint
  • AddTask ssh-git-helper publishenv - set SSH_OPTIONS and GIT_SSH_COMMAND for external binary use
  • AddTask ssh-git-helper delete - delete the temporary hostkeys file; automatically added as a FinalTask

The addhostkeys, loadhostkeys and scan sub-commands all create a known_hosts file that can be used with git-command and ssh-agent for working with git repositories authenticated with ssh. Each of these sub-commands also automatically adds a FinalTask ssh-git-helper delete to remove the temporary file. By using publishenv, the SSH_OPTIONS and GIT_SSH_COMMAND parameters (environment variables) are exported to the pipeline for use by e.g. bash-based tasks using the system ssh and/or git binaries.

Note that <encoded-host-keys> is a single-line string encoded similarly to GOPHER_DEPLOY_KEY; all spaces are replaced with '_', and newlines are replaced with ':'; basically, tr ' \n' '_:'.

git-command - privileged

Usage:

  • AddTask git-command clone <repoURL> <branch> <directory> - Clones a repository from <repoURL> into <directory>. If <branch> is specified, it clones that branch; otherwise, it clones the default branch.
  • AddTask git-command pull <directory> - Pulls the latest changes in the repository located at <directory>.
  • AddTask git-command switch <branch> <directory> - Switches to <branch> in the repository at <directory>. If the branch does not exist locally, it creates it to track the remote branch.
  • AddTask git-command push <branch-if-no-upstream> <commit_msg> <directory> - Commits and pushes changes in the repository at <directory>. If the current branch has no upstream, it pushes to origin/<branch-if-no-upstream> with the provided <commit_msg>; otherwise, it pushes to the tracked remote branch.

The git-command task provides essential Git operations within the pipeline, enabling actions such as cloning repositories, pulling updates, checking out branches, and pushing changes. It is designed for straightforward, non-development workflows to support regular robot operations without the complexity of full Git functionalities.

This task integrates seamlessly with the ssh-agent and ssh-git-helper tasks to manage SSH authentication and host key verification, ensuring secure interactions with Git repositories.

See also:

  • plugins/samples/save.sh - previous job for pushing code to remote git repos

tail-log

Usage: AddTask tail-log or FailTask tail-log

Dump the last 2k chars (in even line increments) to the channel. Normally this is used as a FailTask to show the source of the failure.