Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 14 additions & 1 deletion test-companion/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -67,9 +67,22 @@ from the release you tested; a version without a checksum is refused.
| `workflow` | no | Manual runs only; event-driven runs read the pipeline file |
| `preview` | no | Report what would happen and change nothing |
| `allow-unisolated` | no | `"true"` runs the agent as the job's own user when it cannot be locked down, where it can reach this job's tokens and secrets. Off by default |
| `app-id` / `app-private-key` | no | Post as the GitHub App. Keep the workflow's `permissions:` block: the workflow token is the fallback |
| `app-id` / `app-private-key` | no | Only for your own GitHub App: sign in with its key directly. Without them, the BrowserStack App is used through the token service (see below) |
| `token-broker-url` / `app-slug` | no | Point at a test token service and its App. Leave unset |
| `github-token` | no | The token for the Action's own GitHub calls. Leave it as the default (the workflow token) or use the GitHub App's token, never a personal access token: Test Companion recognises its own comments by their bot account, and a person's token would make them look like that person's |

## Posting as BrowserStack

Install the BrowserStack GitHub App on the repository and keep `id-token: write`
in the job's `permissions:` (the starter workflow has it). There is no key to
store: each run asks GitHub for a short-lived token that says which repository
it is, and BrowserStack's token service trades it for an App token limited to
that one repository, for at most an hour. If the App isn't installed, the job
has no `id-token: write`, or the service can't be reached, the run carries on
with the workflow token and posts as `github-actions[bot]`, with a notice
saying why. Keep the other `permissions:` lines either way: that token is the
fallback.

## Approving a plan

Before a job changes anything, Test Companion posts its plan and waits for
Expand Down
17 changes: 17 additions & 0 deletions test-companion/action.yml
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,21 @@ inputs:
The App's private key. Store it as a repository or organisation secret,
never inline. It is never passed to the agent's shell.
required: false
token-broker-url:
description: >-
Without app-id and app-private-key, the Action signs in as the BrowserStack
GitHub App through BrowserStack's token service, which holds the App's key.
The job needs `permissions: id-token: write`. Leave this unset; it exists to
point at a test service. Must be https.
required: false
default: "https://test-companion.browserstack.com/api/github-app/token"
app-slug:
description: >-
The slug of the App the token service signs for, so commits and comments
are credited to <slug>[bot]. Leave this unset unless the token service is a
test one with its own App.
required: false
default: "browserstack"

workflow:
description: >
Expand Down Expand Up @@ -212,6 +227,8 @@ runs:
TC_ACTION_SELF_WORKFLOW: ${{ inputs.self-workflow-name }}
TC_ACTION_APP_ID: ${{ inputs.app-id }}
TC_ACTION_APP_PRIVATE_KEY: ${{ inputs.app-private-key }}
TC_ACTION_TOKEN_BROKER_URL: ${{ inputs.token-broker-url }}
TC_ACTION_APP_SLUG: ${{ inputs.app-slug }}
TC_ACTION_ALLOW_UNISOLATED: ${{ inputs.allow-unisolated }}
# The `tc --version` line, so a plan records which CLI made it.
TC_ACTION_CLI_VERSION: ${{ steps.install.outputs.cli-version }}
Expand Down
46 changes: 43 additions & 3 deletions test-companion/src/main.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,7 @@ import {
APP_SIGN_IN_BUDGET_MS,
installationLookupMessage,
} from "./app-auth.mjs"
import { appTokenFromBroker, brokerFallbackNotice, appSlugFrom } from "./token-broker.mjs"
import { OUTCOMES, parseSummary, resolveOutcome, checkConclusion, stepShouldFail, approvalWasSpent, runDidNotWork } from "./outcome.mjs"
import {
renderJobSummary,
Expand Down Expand Up @@ -135,7 +136,9 @@ import {
const env = process.env
// Taken before the App token replaces GH_TOKEN and the key is deleted, so both are still hidden.
const STARTUP_SECRETS = secretsFrom(env)
const secretsNow = () => [...STARTUP_SECRETS, ...secretsFrom(env)]
// Credentials received at run time that never sit in env, such as the identity token sent to the token service.
const RECEIVED_SECRETS = []
const secretsNow = () => [...STARTUP_SECRETS, ...RECEIVED_SECRETS, ...secretsFrom(env)]
const REPO = env.GITHUB_REPOSITORY ?? ""
const RUN_URL = `${env.GITHUB_SERVER_URL ?? "https://github.com"}/${REPO}/actions/runs/${env.GITHUB_RUN_ID ?? ""}`
// RUNNER_TEMP is cleared per job; /tmp may hold an earlier job's files on a reused runner.
Expand Down Expand Up @@ -308,10 +311,14 @@ function personTokenLogin() {
return login
}

/** A repo-scoped App installation token, or undefined to fall back to the workflow token. */
/**
* A repo-scoped App installation token, or undefined to fall back to the workflow token.
* With the App's key as inputs (a self-managed App), sign in directly; otherwise ask
* BrowserStack's token service, which holds the key.
*/
async function appInstallationToken() {
const creds = appCredentials(env)
if (!creds) return undefined
if (!creds) return brokeredAppToken()
// Remove the key from the environment so nothing started later, the agent included, inherits it.
delete env.TC_ACTION_APP_PRIVATE_KEY

Expand Down Expand Up @@ -382,6 +389,39 @@ async function appInstallationToken() {
return token
}

/** The App token from BrowserStack's token service, or undefined to fall back to the workflow token. */
async function brokeredAppToken() {
const mask = (secret) => {
console.log(`::add-mask::${secret}`)
RECEIVED_SECRETS.push(secret)
}
let got
try {
got = await appTokenFromBroker({ env, mask })
} catch (e) {
got = { notice: brokerFallbackNotice({ reason: e?.message ?? String(e) }) }
} finally {
// Spent: nothing started later, the agent included, can ask for another identity token.
delete env.ACTIONS_ID_TOKEN_REQUEST_TOKEN
delete env.ACTIONS_ID_TOKEN_REQUEST_URL
}
if (!got.token) {
if (got.notice) notice(got.notice)
return undefined
}
if (got.attempts > 1) notice(`Test Companion: reaching the token service took ${got.attempts} tries.`)

// The service doesn't say which App it signed for; its bot account is <slug>[bot].
const appSlug = appSlugFrom(env.TC_ACTION_APP_SLUG)
const appLogin = `${appSlug}[bot]`
botLogin = appLogin
// The bot account's id makes the noreply email GitHub links to the App.
const user = runGh(["api", `users/${encodeURIComponent(appLogin)}`, "--jq", ".id"], { token: got.token })
if (user.status !== 0) warn(`Test Companion: could not look up ${appLogin}'s account, so commits use the plain Test Companion name.`)
identity = commitIdentity({ appSlug, appUserId: user.status === 0 ? String(user.stdout ?? "").trim() : "" })
return got.token
}

/**
* The settings file from the default branch, so a pull request cannot rewrite the rules for its own run.
* Returns the local path, or undefined (treated as no settings).
Expand Down
162 changes: 162 additions & 0 deletions test-companion/src/token-broker.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,162 @@
/**
* Signing in as the BrowserStack GitHub App without holding its key.
*
* The job asks GitHub for a short-lived identity token (OIDC) that says which
* repository and run it is, addressed to BrowserStack's token service. The
* service checks it and returns an App token limited to this one repository.
* The App's key never leaves the service. Any failure falls back to the
* workflow token, as a job without the App does today.
*/
import { retryDelayMs } from "./app-auth.mjs"

export const DEFAULT_BROKER_URL = "https://test-companion.browserstack.com/api/github-app/token"
/** Who the identity token is addressed to; the service refuses any other. */
export const OIDC_AUDIENCE = "test-companion.browserstack.com"
/** The App's slug, so its bot account is `<slug>[bot]`. */
export const DEFAULT_APP_SLUG = "browserstack"
/** One call gives up after this long; a timeout counts as a network error, so it is retried. */
export const BROKER_CALL_TIMEOUT_MS = 10_000

/** The service's address, or undefined with why: only an https URL with no credentials in it is used. */
export function brokerUrlFrom(input) {
const raw = String(input ?? "").trim() || DEFAULT_BROKER_URL
let url
try {
url = new URL(raw)
} catch {
return { reason: "token-broker-url is not a valid URL" }
}
if (url.protocol !== "https:") return { reason: "token-broker-url must use https" }
if (url.username || url.password) return { reason: "token-broker-url must not contain credentials" }
return { url: url.toString() }
}

/** The App's slug from the input, or the default. Only a GitHub-shaped slug is used. */
export function appSlugFrom(input) {
const slug = String(input ?? "").trim().toLowerCase()
return /^[a-z0-9](?:[a-z0-9-]{0,98}[a-z0-9])?$/.test(slug) ? slug : DEFAULT_APP_SLUG
}

/**
* Where to ask GitHub for the identity token, or undefined when this job can't:
* GitHub only sets these two when the job has `permissions: id-token: write`.
*/
export function oidcRequestFrom(env = {}) {
const requestUrl = String(env.ACTIONS_ID_TOKEN_REQUEST_URL ?? "").trim()
const requestToken = String(env.ACTIONS_ID_TOKEN_REQUEST_TOKEN ?? "").trim()
if (!requestUrl || !requestToken) return undefined
return { requestUrl, requestToken }
}

/** The identity-token request URL with our audience; GitHub's URL already carries a query. */
export function oidcUrlFor(requestUrl, audience = OIDC_AUDIENCE) {
const url = new URL(requestUrl)
url.searchParams.set("audience", audience)
return url.toString()
}

/** A network failure, a 429 or a 5xx may pass on another try; 503 means "turned off" and won't. */
export function isBrokerRetryable(status) {
const s = Number(status)
return s === 0 || s === 429 || (s >= 500 && s <= 599 && s !== 503)
}

/** The one-line notice for falling back to the workflow token. Never contains a token. */
export function brokerFallbackNotice(result) {
const status = Number(result?.status)
if (status === 404) return "Test Companion: the BrowserStack GitHub App isn't installed on this repository; using the workflow token."
if (status === 503) return "Test Companion: App sign-in is turned off; using the workflow token."
const why = result?.reason || (Number.isFinite(status) && status > 0 ? `HTTP ${status}` : "no reply")
return `Test Companion: could not sign in as the GitHub App (${why}); using the workflow token.`
}

const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))

/** One JSON call with a time limit and retries. Returns { ok, status, data, reason, attempts }; never throws. */
async function callJson(url, init, { fetchImpl = fetch, attempts = 3, sleep = defaultSleep, timeoutMs = BROKER_CALL_TIMEOUT_MS } = {}) {
let result
for (let attempt = 1; attempt <= attempts; attempt++) {
result = await callOnce(url, init, { fetchImpl, timeoutMs })
if (result.ok || !isBrokerRetryable(result.status) || attempt === attempts) return { ...result, attempts: attempt }
await sleep(retryDelayMs(result, attempt))
}
return { ...result, attempts }
}

async function callOnce(url, init, { fetchImpl, timeoutMs }) {
const controller = new AbortController()
const timer = setTimeout(() => controller.abort(new Error(`no reply within ${timeoutMs / 1000}s`)), timeoutMs)
try {
let response
try {
response = await fetchImpl(url, { ...init, signal: controller.signal })
} catch (e) {
return { ok: false, status: 0, data: undefined, reason: `could not reach it: ${e?.message ?? e}` }
}
const data = await response.json().catch(() => undefined)
const retryAfter = response.headers?.get?.("retry-after") ?? undefined
return {
ok: response.ok,
status: response.status,
data,
reason: response.ok ? "" : `HTTP ${response.status}`,
...(retryAfter ? { retryAfter } : {}),
}
} finally {
clearTimeout(timer)
}
}

/** Ask GitHub for this job's identity token. Returns { ok, value } or { ok: false, status, reason }. */
export async function requestOidcToken({ requestUrl, requestToken, audience = OIDC_AUDIENCE, ...opts }) {
const r = await callJson(oidcUrlFor(requestUrl, audience), { method: "GET", headers: { Authorization: `bearer ${requestToken}` } }, opts)
const value = r.ok ? r.data?.value : undefined
if (typeof value !== "string" || !value) {
return { ok: false, status: r.status, reason: r.ok ? "GitHub returned no identity token" : `identity token: ${r.reason}` }
}
return { ok: true, value }
}

/** Trade the identity token for an App token. Returns the service's reply as { ok, status, data, reason }. */
export async function requestBrokerToken({ url, oidcToken, ...opts }) {
return callJson(
url,
{ method: "POST", headers: { "Content-Type": "application/json", Accept: "application/json" }, body: JSON.stringify({ oidc_token: oidcToken }) },
opts,
)
}

/**
* The whole exchange. Returns { token, oidcToken } on success, or { notice } to fall back with.
* `mask` is called with each credential the moment it is received, before anything else uses it.
* The service's token must be for this job's repository; any other is refused.
*/
export async function appTokenFromBroker({ env = {}, mask = () => {}, ...opts } = {}) {
const request = oidcRequestFrom(env)
if (!request) {
return {
notice:
"Test Companion: posting as github-actions[bot]. To post as BrowserStack, install the BrowserStack GitHub App " +
"and add `id-token: write` to this job's permissions.",
}
}
const target = brokerUrlFrom(env.TC_ACTION_TOKEN_BROKER_URL)
if (!target.url) return { notice: `Test Companion: ${target.reason}; using the workflow token.` }

const oidc = await requestOidcToken({ ...request, ...opts })
if (!oidc.ok) return { notice: brokerFallbackNotice({ status: oidc.status, reason: oidc.reason }) }
mask(oidc.value)

const got = await requestBrokerToken({ url: target.url, oidcToken: oidc.value, ...opts })
const token = got.ok ? got.data?.token : undefined
if (token) mask(token)
if (!got.ok) return { notice: brokerFallbackNotice(got), attempts: got.attempts }
if (typeof token !== "string" || !token) return { notice: brokerFallbackNotice({ reason: "the reply had no token" }) }

const repo = String(env.GITHUB_REPOSITORY ?? "").toLowerCase()
const issuedFor = String(got.data?.repository ?? "").toLowerCase()
if (!repo || issuedFor !== repo) {
return { notice: brokerFallbackNotice({ reason: "the token was issued for a different repository" }) }
}
return { token, oidcToken: oidc.value, attempts: got.attempts }
}
7 changes: 6 additions & 1 deletion test-companion/starter-workflow.yml
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,10 @@
# Add two secrets under Settings → Secrets and variables → Actions:
# BROWSERSTACK_USERNAME and BROWSERSTACK_ACCESS_KEY.
#
# To have comments, checks and commits show as BrowserStack, install the BrowserStack
# GitHub App on the repository. There's no key to add: the job signs in through
# BrowserStack's token service, using `id-token: write` below.
#
# What runs is set in testcompanion-pipeline.yml, so you can leave this file as it is.
# Every trigger is listed up front; one that matches nothing costs a no-op job.
name: Test Companion
Expand Down Expand Up @@ -67,6 +71,7 @@ jobs:
pull-requests: write # the one comment, and opening a pull request
checks: write # the "Test Companion" check
actions: write # reading the red run, and cancelling one when a PR closes
id-token: write # signing in as the BrowserStack GitHub App, with no key in this repository
steps:
# v4.4.0, pinned to a commit because a tag can be repointed.
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262
Expand All @@ -85,7 +90,7 @@ jobs:
# a version without a checksum is refused.
# cli-version: "1.2.0"
# cli-sha256: "<sha256 of that release for linux-amd64>"
# With the GitHub App installed, uncomment these.
# Only for your own GitHub App instead of BrowserStack's: uncomment these.
# app-id: ${{ secrets.TEST_COMPANION_APP_ID }}
# app-private-key: ${{ secrets.TEST_COMPANION_APP_PRIVATE_KEY }}
# Manual runs only; event-driven runs read the pipeline file.
Expand Down
Loading
Loading