feat: Natively support runner job started/completed hooks (#4260)

Pre and post job hooks were added to github actions to help
administrators run custom scripts at the beginning and end of every job.
As of today the module doesn't support these options out of the box.

Add variables to accept these optional scripts and register the hook in
user-data.

Also add sample hooks to the multi-runner examples.

Related to: #3854

examples/multi-runner/templates/runner-configs/linux-arm64.yaml

@@ -18,3 +18,12 @@ runner_config:
   runners_maximum_count: 1
   delay_webhook_event: 0
   scale_down_schedule_expression: cron(* * * * ? *)
+  runner_hook_job_started: |
+    echo "Running pre job hook as \$(whoami)"
+
+    # Clean github workspace from previous runs
+    if [[ -n "\$GITHUB_WORKSPACE" ]]; do
+      rm -rf "\$GITHUB_WORKSPACE"
+    done
+  runner_hook_job_completed: |
+    echo "Running post job hook as \$(whoami)"

examples/multi-runner/templates/runner-configs/linux-x64-ubuntu.yaml

@@ -52,3 +52,12 @@ runner_config:
       prefix_log_group: true
       file_path: /opt/actions-runner/_diag/Runner_**.log
       log_stream_name: "{instance_id}/runner"
+  runner_hook_job_started: |
+    echo "Running pre job hook as \$(whoami)"
+
+    # Clean github workspace from previous runs
+    if [[ -n "\$GITHUB_WORKSPACE" ]]; do
+      rm -rf "\$GITHUB_WORKSPACE"
+    done
+  runner_hook_job_completed: |
+    echo "Running post job hook as \$(whoami)"

examples/multi-runner/templates/runner-configs/linux-x64.yaml

@@ -29,3 +29,12 @@ runner_config:
     enable: true
     max_attempts: 1
     delay_in_seconds: 180
+  runner_hook_job_started: |
+    echo "Running pre job hook as \$(whoami)"
+
+    # Clean github workspace from previous runs
+    if [[ -n "\$GITHUB_WORKSPACE" ]]; do
+      rm -rf "\$GITHUB_WORKSPACE"
+    done
+  runner_hook_job_completed: |
+    echo "Running post job hook as \$(whoami)"

examples/multi-runner/templates/user-data.sh

@@ -81,4 +81,18 @@ ${post_install}
 
 cd /opt/actions-runner
 
+%{ if hook_job_started != "" }
+cat > /opt/actions-runner/hook_job_started.sh << EOF
+${hook_job_started}
+EOF
+echo ACTIONS_RUNNER_HOOK_JOB_STARTED=/opt/actions-runner/hook_job_started.sh | tee -a /opt/actions-runner/.env
+%{ endif }
+
+%{ if hook_job_completed != "" }
+cat > /opt/actions-runner/hook_job_completed.sh << EOF
+${hook_job_completed}
+EOF
+echo ACTIONS_RUNNER_HOOK_JOB_COMPLETED=/opt/actions-runner/hook_job_completed.sh | tee -a /opt/actions-runner/.env
+%{ endif }
+
 ${start_runner}

main.tf

@@ -249,6 +249,8 @@ module "runners" {
   userdata_content               = var.userdata_content
   userdata_pre_install           = var.userdata_pre_install
   userdata_post_install          = var.userdata_post_install
+  runner_hook_job_started        = var.runner_hook_job_started
+  runner_hook_job_completed      = var.runner_hook_job_completed
   key_name                       = var.key_name
   runner_ec2_tags                = var.runner_ec2_tags
 

modules/multi-runner/runners.tf

@@ -86,13 +86,15 @@ module "runners" {
   role_path                 = var.role_path
   role_permissions_boundary = var.role_permissions_boundary
 
-  enable_userdata       = each.value.runner_config.enable_userdata
-  userdata_template     = each.value.runner_config.userdata_template
-  userdata_content      = each.value.runner_config.userdata_content
-  userdata_pre_install  = each.value.runner_config.userdata_pre_install
-  userdata_post_install = each.value.runner_config.userdata_post_install
-  key_name              = var.key_name
-  runner_ec2_tags       = each.value.runner_config.runner_ec2_tags
+  enable_userdata           = each.value.runner_config.enable_userdata
+  userdata_template         = each.value.runner_config.userdata_template
+  userdata_content          = each.value.runner_config.userdata_content
+  userdata_pre_install      = each.value.runner_config.userdata_pre_install
+  userdata_post_install     = each.value.runner_config.userdata_post_install
+  runner_hook_job_started   = each.value.runner_config.runner_hook_job_started
+  runner_hook_job_completed = each.value.runner_config.runner_hook_job_completed
+  key_name                  = var.key_name
+  runner_ec2_tags           = each.value.runner_config.runner_ec2_tags
 
   create_service_linked_role_spot = each.value.runner_config.create_service_linked_role_spot
 

modules/multi-runner/variables.tf

@@ -78,6 +78,8 @@ variable "multi_runner_config" {
       cloudwatch_config                       = optional(string, null)
       userdata_pre_install                    = optional(string, "")
       userdata_post_install                   = optional(string, "")
+      runner_hook_job_started                 = optional(string, "")
+      runner_hook_job_completed               = optional(string, "")
       runner_ec2_tags                         = optional(map(string), {})
       runner_iam_role_managed_policy_arns     = optional(list(string), [])
       vpc_id                                  = optional(string, null)

modules/runners/main.tf

@@ -54,7 +54,9 @@ locals {
       S3_LOCATION_RUNNER_DISTRIBUTION = local.s3_location_runner_distribution
       RUNNER_ARCHITECTURE             = var.runner_architecture
     })
-    post_install = var.userdata_post_install
+    post_install       = var.userdata_post_install
+    hook_job_started   = var.runner_hook_job_started
+    hook_job_completed = var.runner_hook_job_completed
     start_runner = templatefile(local.userdata_start_runner[var.runner_os], {
       metadata_tags = var.metadata_options != null ? var.metadata_options.instance_metadata_tags : "enabled"
     })

modules/runners/templates/user-data.sh

@@ -62,4 +62,20 @@ ${install_runner}
 
 ${post_install}
 
+# Register runner job hooks
+# Ref: https://github.com/actions/runner/blob/main/docs/adrs/1751-runner-job-hooks.md
+%{ if hook_job_started != "" }
+cat > /opt/actions-runner/hook_job_started.sh << EOF
+${hook_job_started}
+EOF
+echo ACTIONS_RUNNER_HOOK_JOB_STARTED=/opt/actions-runner/hook_job_started.sh | tee -a /opt/actions-runner/.env
+%{ endif }
+
+%{ if hook_job_completed != "" }
+cat > /opt/actions-runner/hook_job_completed.sh << EOF
+${hook_job_completed}
+EOF
+echo ACTIONS_RUNNER_HOOK_JOB_COMPLETED=/opt/actions-runner/hook_job_completed.sh | tee -a /opt/actions-runner/.env
+%{ endif }
+
 ${start_runner}

modules/runners/variables.tf

@@ -172,6 +172,18 @@ variable "userdata_post_install" {
   default     = ""
 }
 
+variable "runner_hook_job_started" {
+  description = "Script to be ran in the runner environment at the beginning of every job"
+  type        = string
+  default     = ""
+}
+
+variable "runner_hook_job_completed" {
+  description = "Script to be ran in the runner environment at the end of every job"
+  type        = string
+  default     = ""
+}
+
 variable "sqs_build_queue" {
   description = "SQS queue to consume accepted build events."
   type = object({

variables.tf

@@ -280,6 +280,18 @@ variable "userdata_post_install" {
   description = "Script to be ran after the GitHub Actions runner is installed on the EC2 instances"
 }
 
+variable "runner_hook_job_started" {
+  type        = string
+  default     = ""
+  description = "Script to be ran in the runner environment at the beginning of every job"
+}
+
+variable "runner_hook_job_completed" {
+  type        = string
+  default     = ""
+  description = "Script to be ran in the runner environment at the end of every job"
+}
+
 variable "idle_config" {
   description = "List of time periods, defined as a cron expression, to keep a minimum amount of runners active instead of scaling down to 0. By defining this list you can ensure that in time periods that match the cron expression within 5 seconds a runner is kept idle."
   type = list(object({