diff --git a/README.md b/README.md index 96b2a70..2f04109 100644 --- a/README.md +++ b/README.md @@ -11,6 +11,11 @@ Nix pointed at our substituters, and push what it built to the shared binary cache. Keeping one copy here means a change to the cache endpoint, a key rotation, or a pinned installer bump lands in one place instead of nine. +The same goes for GitHub App tokens. A pull request opened with the workflow's +own `GITHUB_TOKEN` starts no workflows, so a bot that opens PRs needs an App +token, and the App's key lives in AWS SSM, GCP Secret Manager or a repository +secret depending on the repository. `app-token` reads it from any of them. + ## Install Nothing to install — reference an action by path and ref: @@ -51,10 +56,25 @@ jobs: token: ${{ secrets.NIX_CACHE_PUSH_TOKEN }} ``` -| Action | Purpose | -| ---------------------------------------------- | ------------------------------------------------ | -| [`nix-setup`](nix-setup/action.yaml) | install Nix, wire up substituters and cache auth | -| [`nix-cache-push`](nix-cache-push/action.yaml) | upload locally-built paths to the cache | +| Action | Purpose | +| ---------------------------------------------- | -------------------------------------------------------- | +| [`nix-setup`](nix-setup/action.yaml) | install Nix, wire up substituters and cache auth | +| [`nix-cache-push`](nix-cache-push/action.yaml) | upload locally-built paths to the cache | +| [`app-token`](app-token/action.yaml) | GitHub App token, key read from a secret, AWS SSM or GCP | + +An App token, with the key in the repository's own secrets: + +```yaml +- id: app-token + uses: genlayerlabs/github-actions/app-token@main + with: + client_id: ${{ vars.PR_BOT_CLIENT_ID }} + private_key: ${{ secrets.PR_BOT_PRIVATE_KEY }} + +- run: gh pr create --fill + env: + GH_TOKEN: ${{ steps.app-token.outputs.token }} +``` The cache is **private** — `nix-setup` needs `cache_pull_token` or it will build everything from source. See [nix-cache.md](docs/using/nix-cache.md) for what the diff --git a/app-token/action.yaml b/app-token/action.yaml new file mode 100644 index 0000000..ef01966 --- /dev/null +++ b/app-token/action.yaml @@ -0,0 +1,207 @@ +name: GenLayer app token +description: >- + Generate a short-lived GitHub App installation token from the app's client ID + and private key, wherever they are kept: passed in directly, in AWS SSM, or in + GCP Secret Manager. +inputs: + client_id: + description: >- + the app's client ID, passed in directly (a repository variable). Set it + with `private_key`, and set no other source. A wrong value fails the job + when the token is generated. + required: false + default: "" + private_key: + description: >- + the app's private key, passed in directly (a repository secret). A pull + request from a fork gets no secrets: the key is then empty and the job + fails, saying so. + required: false + default: "" + client_id_ssm_parameter: + description: >- + SSM parameter holding the client ID. Set it with + `private_key_ssm_parameter`, and set no other source. A parameter that + cannot be read, or still holds `CHANGE_ME`, fails the job. + required: false + default: "" + private_key_ssm_parameter: + description: SSM SecureString parameter holding the private key + required: false + default: "" + aws_role_arn: + description: >- + IAM role the job assumes with its GitHub OIDC token to read the SSM + parameters; the job needs `permissions: id-token: write`. Empty uses the + runner's own AWS credentials, which only a self-hosted runner has (an EC2 + instance profile); on a GitHub-hosted runner the read then fails. + required: false + default: "" + aws_region: + description: region of the SSM parameters + required: false + default: us-east-1 + gcp_wif_provider: + description: >- + Workload Identity Federation provider the job authenticates to GCP with; + the job needs `permissions: id-token: write`. Set it with + `gcp_service_account`, `gcp_project_id`, `client_id_gcp_secret` and + `private_key_gcp_secret`, and set no other source. A repository the + provider's attribute condition does not allow fails at authentication. + required: false + default: "" + gcp_service_account: + description: service account the job impersonates; it needs access to both secrets + required: false + default: "" + gcp_project_id: + description: GCP project holding the secrets + required: false + default: "" + client_id_gcp_secret: + description: Secret Manager secret holding the client ID + required: false + default: "" + private_key_gcp_secret: + description: Secret Manager secret holding the private key + required: false + default: "" + owner: + description: >- + owner of the app installation. With no `repositories`, the token reaches + every repository the app is installed on there. + required: false + default: genlayerlabs + repositories: + description: >- + comma-separated repositories (names only) to limit the token to. A + repository the app is not installed on fails the job. + required: false + default: "" +outputs: + token: + description: >- + The installation token. It expires after an hour and is revoked when the + job ends. A pull request it opens, or a push it makes, starts workflows, + unlike one made with the workflow's own GITHUB_TOKEN. + value: ${{ steps.token.outputs.token }} + +runs: + using: composite + steps: + # No `-x`: the private key passes through this step. + - id: source + shell: bash -eo pipefail {0} + env: + CLIENT_ID: ${{ inputs.client_id }} + PRIVATE_KEY: ${{ inputs.private_key }} + CLIENT_ID_SSM: ${{ inputs.client_id_ssm_parameter }} + PRIVATE_KEY_SSM: ${{ inputs.private_key_ssm_parameter }} + AWS_ROLE_ARN: ${{ inputs.aws_role_arn }} + AWS_REGION_INPUT: ${{ inputs.aws_region }} + GCP_WIF_PROVIDER: ${{ inputs.gcp_wif_provider }} + GCP_SERVICE_ACCOUNT: ${{ inputs.gcp_service_account }} + GCP_PROJECT_ID: ${{ inputs.gcp_project_id }} + CLIENT_ID_GCP: ${{ inputs.client_id_gcp_secret }} + PRIVATE_KEY_GCP: ${{ inputs.private_key_gcp_secret }} + run: | + # Each source is a group of inputs: the one with any input set is the + # source, and all of its inputs must be set. + sources=() + [ -n "$CLIENT_ID$PRIVATE_KEY" ] && sources+=(direct) + [ -n "$CLIENT_ID_SSM$PRIVATE_KEY_SSM" ] && sources+=(aws) + [ -n "$GCP_WIF_PROVIDER$GCP_SERVICE_ACCOUNT$GCP_PROJECT_ID$CLIENT_ID_GCP$PRIVATE_KEY_GCP" ] && sources+=(gcp) + if [ "${#sources[@]}" -ne 1 ]; then + echo "::error::set the inputs of exactly one source (client_id + private_key, the *_ssm_parameter pair, or the gcp_* inputs); got: ${sources[*]:-none}" + exit 1 + fi + missing=() + case "${sources[0]}" in + direct) + [ -n "$CLIENT_ID" ] || missing+=(client_id) + [ -n "$PRIVATE_KEY" ] || missing+=("private_key (a fork's pull request gets no secrets)") + ;; + aws) + [ -n "$CLIENT_ID_SSM" ] || missing+=(client_id_ssm_parameter) + [ -n "$PRIVATE_KEY_SSM" ] || missing+=(private_key_ssm_parameter) + ;; + gcp) + [ -n "$GCP_WIF_PROVIDER" ] || missing+=(gcp_wif_provider) + [ -n "$GCP_SERVICE_ACCOUNT" ] || missing+=(gcp_service_account) + [ -n "$GCP_PROJECT_ID" ] || missing+=(gcp_project_id) + [ -n "$CLIENT_ID_GCP" ] || missing+=(client_id_gcp_secret) + [ -n "$PRIVATE_KEY_GCP" ] || missing+=(private_key_gcp_secret) + ;; + esac + if [ "${#missing[@]}" -gt 0 ]; then + printf -v list '%s, ' "${missing[@]}" + echo "::error::the ${sources[0]} source is missing: ${list%, }" + exit 1 + fi + echo "source=${sources[0]}" >> "$GITHUB_OUTPUT" + + if [ "${sources[0]}" = aws ]; then + work="$(mktemp -d "${RUNNER_TEMP:-/tmp}/app-token.XXXXXX")" + trap 'rm -rf "$work"' EXIT + for pair in "client_id:$CLIENT_ID_SSM" "private_key:$PRIVATE_KEY_SSM"; do + name="${pair%%:*}" + parameter="${pair#*:}" + rc=0 + "$GITHUB_ACTION_PATH/../support/scripts/read-ssm-token.sh" \ + "$AWS_ROLE_ARN" "$AWS_REGION_INPUT" "$parameter" "$work/$name" || rc=$? + case "$rc" in + 0) ;; + 3) + echo "::error::no OIDC token to read $parameter; add 'permissions: id-token: write' to the job (a fork's pull request gets none)" + exit 1 + ;; + *) + echo "::error::could not read $parameter; see the message above" + exit 1 + ;; + esac + # A random delimiter: a fixed one could appear in the value and end + # the output early. + delimiter="EOF_$(od -An -tx1 -N16 /dev/urandom | tr -d ' \n')" + { + echo "$name<<$delimiter" + cat "$work/$name" + echo + echo "$delimiter" + } >> "$GITHUB_OUTPUT" + done + fi + + # Pinned by commit: a tag can be moved, and these steps handle the app key. + - if: steps.source.outputs.source == 'gcp' + uses: google-github-actions/auth@7c6bc770dae815cd3e89ee6cdf493a5fab2cc093 # v3.0.0 + with: + workload_identity_provider: ${{ inputs.gcp_wif_provider }} + service_account: ${{ inputs.gcp_service_account }} + + - id: gcp + if: steps.source.outputs.source == 'gcp' + uses: google-github-actions/get-secretmanager-secrets@bc9c54b29fdffb8a47776820a7d26e77b379d262 # v3.0.0 + with: + secrets: |- + client_id:${{ inputs.gcp_project_id }}/${{ inputs.client_id_gcp_secret }} + private_key:${{ inputs.gcp_project_id }}/${{ inputs.private_key_gcp_secret }} + + # A mask covers one line. The secret action masks the key as a whole, which + # leaves each of its lines readable if something prints them one by one. + - if: steps.source.outputs.source == 'gcp' + shell: bash -eo pipefail {0} + env: + PRIVATE_KEY: ${{ steps.gcp.outputs.private_key }} + run: | + while IFS= read -r line; do + if [ -n "$line" ]; then echo "::add-mask::$line"; fi + done <<<"$PRIVATE_KEY" + + - id: token + uses: actions/create-github-app-token@64ab729a6294000f5aa4a4bc0b73d1f32bc45510 # v3.3.0 + with: + client-id: ${{ inputs.client_id || steps.source.outputs.client_id || steps.gcp.outputs.client_id }} + private-key: ${{ inputs.private_key || steps.source.outputs.private_key || steps.gcp.outputs.private_key }} + owner: ${{ inputs.owner }} + repositories: ${{ inputs.repositories }} diff --git a/docs/using/actions.md b/docs/using/actions.md index 8110a60..21f1849 100644 --- a/docs/using/actions.md +++ b/docs/using/actions.md @@ -104,3 +104,61 @@ Notes: step; any other job without an OIDC token fails. - Requires `jq` and a flake in `$GITHUB_WORKSPACE` (`--inputs-from .` resolves the attic client through your lock file rather than the mutable registry). + +## app-token + +Generates a GitHub App installation token. The App's client ID and private key +come from exactly one source: passed in directly, AWS SSM, or GCP Secret +Manager. A pull request opened, or a push made, with this token starts +workflows; one made with the workflow's own `GITHUB_TOKEN` does not. + +| Input | Default | Description | +| --------------------------- | -------------- | ------------------------------------------------------------------------------------------------ | +| `client_id` | `""` | direct: the App's client ID (a repository variable) | +| `private_key` | `""` | direct: the App's private key (a repository secret) | +| `client_id_ssm_parameter` | `""` | aws: SSM parameter holding the client ID | +| `private_key_ssm_parameter` | `""` | aws: SSM SecureString parameter holding the private key | +| `aws_role_arn` | `""` | aws: role the job assumes with its OIDC token; empty uses the runner's own AWS credentials | +| `aws_region` | `us-east-1` | aws: region of the SSM parameters | +| `gcp_wif_provider` | `""` | gcp: Workload Identity Federation provider; needs `id-token: write` | +| `gcp_service_account` | `""` | gcp: service account to impersonate, with access to both secrets | +| `gcp_project_id` | `""` | gcp: project holding the secrets | +| `client_id_gcp_secret` | `""` | gcp: Secret Manager secret holding the client ID | +| `private_key_gcp_secret` | `""` | gcp: Secret Manager secret holding the private key | +| `owner` | `genlayerlabs` | owner of the App installation | +| `repositories` | `""` | comma-separated repository names to limit the token to; empty reaches every repository installed | + +Outputs: + +| Output | Description | +| ------- | -------------------------------------------------------------------- | +| `token` | the installation token; expires after an hour, revoked when job ends | + +```yaml +# The key in AWS SSM, read with an OIDC role on a GitHub-hosted runner +- id: app-token + uses: genlayerlabs/github-actions/app-token@main + with: + client_id_ssm_parameter: /devexp-dev/e2e-runner/secrets/app-client-id + private_key_ssm_parameter: /devexp-dev/e2e-runner/secrets/app-private-key + aws_role_arn: arn:aws:iam:::role/ +``` + +Notes: + +- The source is the group of inputs that has any value. Setting inputs of two + sources, or only part of one, fails the job and names what is missing. +- A pull request from a fork gets no secrets and no OIDC token, so no source + works there; the job fails, saying so. +- `aws` without `aws_role_arn` relies on the runner's own credentials: an EC2 + runner's instance profile. A GitHub-hosted runner has none. With a role, the + read goes through `support/scripts/read-ssm-token.sh`, as for `nix-setup`. + A parameter still holding `CHANGE_ME` fails the job. +- `gcp` authenticates with `google-github-actions/auth`, which writes a + credentials file in the workspace for the rest of the job, like any job that + uses that action. The provider's attribute condition must allow the calling + repository (genlayer-wif-management). +- The private key is masked line by line whichever source it comes from: a mask + covers one line, so a key masked as a whole stays readable line by line. +- Without `repositories`, the token reaches every repository the App is + installed on under `owner`. Limit it when the job needs only some. diff --git a/support/scripts/read-ssm-token.sh b/support/scripts/read-ssm-token.sh index 66a5b7d..5add22a 100755 --- a/support/scripts/read-ssm-token.sh +++ b/support/scripts/read-ssm-token.sh @@ -1,13 +1,18 @@ #!/usr/bin/env bash -# Read one SecureString parameter from AWS SSM with the job's GitHub OIDC token, -# for the SSM inputs of nix-setup and nix-cache-push. +# Read one SecureString parameter from AWS SSM, for the SSM inputs of nix-setup, +# nix-cache-push and app-token. # # read-ssm-token.sh ROLE_ARN REGION PARAMETER OUT_FILE # -# Writes the value to OUT_FILE (mode 0600) and masks it in the job log. -# Exit 0: read. Exit 3: the job has no OIDC token (a fork's pull request, or a -# job without `permissions: id-token: write`); the caller decides which. Exit 1: -# any other failure, with the reason on stderr. +# With a ROLE_ARN, the job's GitHub OIDC token is exchanged for that role. With +# an empty ROLE_ARN, the runner's own AWS credentials are used (an EC2 runner's +# instance profile); a GitHub-hosted runner has none. +# +# Writes the value to OUT_FILE (mode 0600) and masks it in the job log one line +# at a time, so a multi-line value such as a private key stays masked. +# Exit 0: read. Exit 3: a ROLE_ARN was given but the job has no OIDC token (a +# fork's pull request, or a job without `permissions: id-token: write`); the +# caller decides which. Exit 1: any other failure, with the reason on stderr. # # No `set -x`: the OIDC token, the role credentials and the value all pass # through this script. None of them reaches argv, which any user can read. @@ -22,7 +27,7 @@ region=$2 parameter=$3 out=$4 -if [ -z "${ACTIONS_ID_TOKEN_REQUEST_URL:-}" ] || [ -z "${ACTIONS_ID_TOKEN_REQUEST_TOKEN:-}" ]; then +if [ -n "$role" ] && { [ -z "${ACTIONS_ID_TOKEN_REQUEST_URL:-}" ] || [ -z "${ACTIONS_ID_TOKEN_REQUEST_TOKEN:-}" ]; }; then exit 3 fi @@ -36,42 +41,51 @@ done work="$(mktemp -d "${RUNNER_TEMP:-/tmp}/ssm-token.XXXXXX")" trap 'rm -rf "$work"' EXIT -# The request token reaches curl through a config on stdin. -if ! printf 'header = "Authorization: bearer %s"\n' "$ACTIONS_ID_TOKEN_REQUEST_TOKEN" | - curl -sSf -K - "${ACTIONS_ID_TOKEN_REQUEST_URL}&audience=sts.amazonaws.com" | - jq -er .value >"$work/jwt"; then - echo "could not get an OIDC token from GitHub" >&2 - exit 1 -fi -echo "::add-mask::$(cat "$work/jwt")" +if [ -n "$role" ]; then + # The request token reaches curl through a config on stdin. + if ! printf 'header = "Authorization: bearer %s"\n' "$ACTIONS_ID_TOKEN_REQUEST_TOKEN" | + curl -sSf -K - "${ACTIONS_ID_TOKEN_REQUEST_URL}&audience=sts.amazonaws.com" | + jq -er .value >"$work/jwt"; then + echo "could not get an OIDC token from GitHub" >&2 + exit 1 + fi + echo "::add-mask::$(cat "$work/jwt")" -if ! aws sts assume-role-with-web-identity \ - --region "$region" \ - --role-arn "$role" \ - --role-session-name "nix-cache-${GITHUB_RUN_ID:-local}" \ - --web-identity-token "file://$work/jwt" \ - --duration-seconds 900 \ - --query Credentials --output json >"$work/creds"; then - echo "could not assume $role (is this repository and ref in its trust policy?)" >&2 - exit 1 + if ! aws sts assume-role-with-web-identity \ + --region "$region" \ + --role-arn "$role" \ + --role-session-name "github-actions-${GITHUB_RUN_ID:-local}" \ + --web-identity-token "file://$work/jwt" \ + --duration-seconds 900 \ + --query Credentials --output json >"$work/creds"; then + echo "could not assume $role (is this repository and ref in its trust policy?)" >&2 + exit 1 + fi + AWS_ACCESS_KEY_ID="$(jq -r .AccessKeyId "$work/creds")" + AWS_SECRET_ACCESS_KEY="$(jq -r .SecretAccessKey "$work/creds")" + AWS_SESSION_TOKEN="$(jq -r .SessionToken "$work/creds")" + echo "::add-mask::$AWS_SECRET_ACCESS_KEY" + echo "::add-mask::$AWS_SESSION_TOKEN" + export AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN + source="$role" +else + source="the runner's own AWS credentials" fi -key_id="$(jq -r .AccessKeyId "$work/creds")" -secret="$(jq -r .SecretAccessKey "$work/creds")" -session="$(jq -r .SessionToken "$work/creds")" -echo "::add-mask::$secret" -echo "::add-mask::$session" -if ! value="$(AWS_ACCESS_KEY_ID="$key_id" AWS_SECRET_ACCESS_KEY="$secret" AWS_SESSION_TOKEN="$session" \ - aws ssm get-parameter --region "$region" --name "$parameter" --with-decryption \ +if ! value="$(aws ssm get-parameter --region "$region" --name "$parameter" --with-decryption \ --query Parameter.Value --output text)"; then - echo "could not read $parameter with $role" >&2 + echo "could not read $parameter with $source" >&2 exit 1 fi if [ -z "$value" ] || [ "$value" = "CHANGE_ME" ]; then - echo "$parameter still holds its Terraform placeholder; the cache host has not minted it yet" >&2 + echo "$parameter still holds its Terraform placeholder; its real value has not been set yet" >&2 exit 1 fi -echo "::add-mask::$value" +# A mask covers one line: masking a multi-line value at once would leave every +# line after the first readable in the log. +while IFS= read -r line; do + if [ -n "$line" ]; then echo "::add-mask::$line"; fi +done <<<"$value" ( umask 077