gm3dmo · gm3dmo · Apr 5, 2025 · Apr 5, 2025 · Apr 5, 2025
diff --git a/create-an-organization-secret-for-app-private-key.rb b/create-an-organization-secret-for-app-private-key.rb
@@ -3,15 +3,43 @@
 
 # You will likely need to `gem install rbnacl` for this script to work.
 
-org_public_key = ARGV[0]
+# Check for required environment variables
+unless ENV["private_pem_file"]
+  STDERR.puts "Error: private_pem_file environment variable is not set. Please set it to the path of your private key file."
+  exit 1
+end
 
-key = Base64.decode64(org_public_key)
-public_key = RbNaCl::PublicKey.new(key)
+# Check if the private key file exists
+private_key_path = File.join(ENV["HOME"], ENV["private_pem_file"])
+unless File.exist?(private_key_path)
+  STDERR.puts "Error: Private key file not found at #{private_key_path}"
+  exit 2
+end
 
-box = RbNaCl::Boxes::Sealed.from_public_key(public_key)
+# Check if organization public key is provided
+unless ARGV[0]
+  STDERR.puts "Error: Organization public key not provided. Usage: ruby script.rb <org_public_key>"
+  exit 3
+end
 
-secret = File.read(ENV["HOME"] + '/' + ENV["private_pem_file"])
+begin
+  org_public_key = ARGV[0]
+  key = Base64.decode64(org_public_key)
+  public_key = RbNaCl::PublicKey.new(key)
 
-encrypted_secret = box.encrypt(secret)
+  box = RbNaCl::Boxes::Sealed.from_public_key(public_key)
 
-puts Base64.strict_encode64(encrypted_secret)
+  secret = File.read(private_key_path)
+  encrypted_secret = box.encrypt(secret)
+
+  puts Base64.strict_encode64(encrypted_secret)
+rescue RbNaCl::CryptoError => e
+  STDERR.puts "Error: Failed to encrypt secret - #{e.message}"
+  exit 4
+rescue ArgumentError => e
+  STDERR.puts "Error: Invalid organization public key - #{e.message}"
+  exit 5
+rescue => e
+  STDERR.puts "Error: #{e.message}"
+  exit 6
+end
diff --git a/create-an-organization-secret-for-app-private-key.sh b/create-an-organization-secret-for-app-private-key.sh
@@ -3,12 +3,40 @@
 # https://docs.github.com/en/enterprise-cloud@latest/rest/actions/secrets?apiVersion=2022-11-28#create-or-update-an-organization-secret
 # PUT /orgs/{org}/actions/secrets/{secret_name}
 
+# Ensure the private_pem_file variable is exported
+export private_pem_file
 
 secret_name=${app_cert_secret_name}
 visibility="all"
 key_id=$(./get-an-organization-public-key.sh | jq -r '.key_id')
 org_public_key=$(./get-an-organization-public-key.sh | jq -r '.key')
+
+# Encrypt the secret and handle any errors
 encrypted_value=$(ruby create-an-organization-secret-for-app-private-key.rb ${org_public_key})
+exit_code=$?
+
+case $exit_code in
+    0)  # Success, continue
+        ;;
+    1)  echo "Error: private_pem_file environment variable is not set"
+        exit 1
+        ;;
+    2)  echo "Error: Private key file not found"
+        exit 2
+        ;;
+    3)  echo "Error: Organization public key not provided"
+        exit 3
+        ;;
+    4)  echo "Error: Failed to encrypt secret"
+        exit 4
+        ;;
+    5)  echo "Error: Invalid organization public key"
+        exit 5
+        ;;
+    *)  echo "Error: Unknown error occurred (exit code: $exit_code)"
+        exit $exit_code
+        ;;
+esac
 
 json_file=tmp/create-or-update-an-organization-secret.sh
 jq -n \

diff --git a/setup.md b/setup.md
@@ -0,0 +1,99 @@
+## Configuring The Power
+
+### Prerequisites
+* Linux/Mac/GitHub Codespace
+* A GitHub Enterprise Server or dotcom org with a Enterprise admin user name and password 
+* A `jq` command on your client:
+
+#### A note about Bash
+
+A few scripts use arrays in bash and for those you'll need to have bash 5.x. The bash delivered on Mac OS is 3.2 so `brew install bash` may be needed if you want to use scripts that contain `declare -A` then you can use `/opt/homebrew/bin/bash`. These scripts were tested with 5.2.37 on Mac:
+
+```
+bash --version
+GNU bash, version 5.2.37(1)-release (aarch64-apple-darwin24.0.0)
+Copyright (C) 2022 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
+```
+
+#### jq
+
+```
+brew install jq
+```
+
+#### Python
+
+* A Python >3.6 interpreter on your Mac.
+
+####  Ruby & Ruby Gems 
+Use the 'brew" version of ruby not the much older version as delivered on Mac OS X. This one seems to work well:
+
+```
+ruby 3.4.2 (2025-02-15 revision d2930f8e7a) +PRISM [arm64-darwin24]
+```
+
+* The [JWT Rubygem](https://rubygems.org/gems/jwt) required for [GitHub App authentication](https://github.com/gm3dmo/the-power/blob/main/docs/setting-up-a-gh-app.md#using-a-github-app-with-the-power):
+
+```
+sudo gem install jwt
+```
+
+#### Personal Access Token (PAT)
+* [Create your token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). In GitHub Enterprise (give it all the scopes. Be careful and give the token an expiry date if running on GitHub.com. Strongly recommend a token with short expiry time. If you find yourself creating a lot of tokens on a regular basis, then this tip for [selecting all checkboxes on](https://gist.github.com/gm3dmo/e085294a622c1c72eec0e8b48d72b092) may be useful.
+
+### Configure The Power with `configure.py`
+
+### Client side setup
+- Download the [latest release](https://github.com/gm3dmo/the-power/releases/latest).
+- Unzip the release file to a directory of your choice.
+- Change into the the directory and version of the power.
+- Run [`configure.py`](/configure.py) to generate the `.gh-api-examples.conf` file. This file feeds variables to the scripts in The Power.:
+
+```bash
+python3 configure.py
+```
+
+`configure.py` asks questions, You need to provide your token and hostname of your
+GHE server or enter `api.github.com` if you are using GitHub.com enter `api.github.com` as the hostname.
+
+```
+Enter GHE Hostname: myserver.example.com
+Enter token: ***cc2d128a
+```
+
+* If you want a different team name,  you can edit  `.gh-api-examples.conf` with an editor of your choice.
+
+
+### `configure.py` can run without interaction from the command line:
+Non-interactive values can be specified on the command line in order to use The Power in a custom automation:
+
+```
+python3 configure.py --hostname myserver.example.com \
+                     --token ghp_****************************wh3Ybleu \
+                     --webhook-url https://events.hookdeck.com/e/src_1hm2RSyiguMW
+```
+The `--primer` flag may also be of interest. Provide the name of a primer script which will be executed when `configure.py` is complete.
+
+Optionally, edit  `.gh-api-examples.conf` to add any extra customizations you want to support.
+
+
+### Applying a build to a GHE server
+
+```
+bash build-all.sh
+```
+
+#### Screen recording `build-all.sh` on GitHub Enterprise Server
+
+[![asciicast](https://asciinema.org/a/QMvQI0AcRUCpTzmxUW4GQB0GX.svg)](https://asciinema.org/a/QMvQI0AcRUCpTzmxUW4GQB0GX)
+
+### Applying a build to an organization on GitHub.com
+
+```
+bash build-testcase
+```
+
+#### Screen recording build-testcase on GitHub.com
+
+[![asciicast](https://asciinema.org/a/djiHmfyYAFhCKlfuWLbACZrrf.svg)](https://asciinema.org/a/djiHmfyYAFhCKlfuWLbACZrrf)