Skip to content

Externally managed SSM secrets

This example is based on the default setup, but shows how to use configure runners with already existing SSM parameters that you'd have created manually.

Manually creating the SSM parameters that hold the configuration of your GitHub App avoids leaking critical plain text values in your terraform state and version control system. This is a recommended security practice for handling sensitive credentials.

Prerequisites

To configure GitHub App credentials in AWS, you have two options:

1. Using the ssm.sh script

  • Edit ssm.sh and set your values
  • Run: source ssm.sh
  • Then run your Terraform commands (terraform plan / terraform apply)

2. Create them manually via the AWS console (or the aws-cli)

  • Create the following SSM parameters on the AWS console:
/github-action-runners/app/github_app_id           (Your GitHub App ID)
/github-action-runners/app/github_app_key_base64   (Your GitHub App Private Key)
/github-action-runners/app/github_app_webhook_secret (Your Installation ID)

Example using AWS CLI:

   # GitHub App ID
   aws ssm put-parameter \
     --name "/github-action-runners/app/github_app_id" \
     --value "YOUR_APP_ID" \
     --type "SecureString"

   # GitHub App Private Key
   aws ssm put-parameter \
     --name "/github-action-runners/app/github_app_key_base64" \
     --value "YOUR_PRIVATE_KEY" \
     --type "SecureString"

   # GitHub App Installation ID
   aws ssm put-parameter \
     --name "/github-action-runners/app/github_app_webhook_secret" \
     --value "YOUR_INSTALLATION_ID" \
     --type "SecureString"

Usages

Steps for the full setup, such as creating a GitHub app can be found in the root module's README. First download the Lambda releases from GitHub. Alternatively you can build the lambdas locally with Node or Docker, there is a simple build script in <root>/.ci/build.sh. In the main.tf you can simply remove the location of the lambda zip files, the default location will work in this case.

This example assumes local built lambda's available. Ensure you have built the lambda's. Alternativly you can downlowd the lambda's. The version needs to be set to a GitHub release version, see https://github.com/philips-labs/terraform-aws-github-runner/releases

cd ../lambdas-download
terraform init
terraform apply -var=module_version=<VERSION>
cd -

Before running Terraform, ensure the GitHub app is configured. See the configuration details for more details.

terraform init
terraform apply

The example will try to update the webhook of your GitHub. In case the update fails the apply will not fail. You can receive the webhook details by running:

terraform output -raw webhook_secret

Requirements

Name Version
terraform >= 1.3.0
aws ~> 5.27
local ~> 2.0
random ~> 3.0

Providers

No providers.

Modules

Name Source Version
base ../base n/a
runners ../../ n/a

Resources

No resources.

Inputs

Name Description Type Default Required
aws_region AWS region. string "eu-west-1" no
environment Environment name, used as prefix. string null no
github_app_ssm_parameters SSM parameters details for the GitHub App, that you've created manually on AWS. 
object({
    key_base64 = optional(object({
      arn  = string
      name = string
    }))
    id = optional(object({
      arn  = string
      name = string
    }))
    webhook_secret = optional(object({
      arn  = string
      name = string
    }))
  })
 {} no

Outputs

Name Description
note n/a
runners n/a
webhook_endpoint n/a