* feat: verify Helm downloads and support fallback mirrors * fix: strengthen Helm download fallback * docs: align mirror example with Helm fallback * fix: preserve custom mirror checksum compatibility * fix: warn for missing checksums in auto mode
548 lines
18 KiB
TypeScript
548 lines
18 KiB
TypeScript
// Copyright (c) Microsoft Corporation.
|
|
// Licensed under the MIT license.
|
|
|
|
import * as os from 'os'
|
|
import * as path from 'path'
|
|
import * as util from 'util'
|
|
import * as fs from 'fs'
|
|
import {createHash} from 'crypto'
|
|
|
|
import * as toolCache from '@actions/tool-cache'
|
|
import * as core from '@actions/core'
|
|
|
|
const helmToolName = 'helm'
|
|
export const stableHelmVersion = 'v4.3.1'
|
|
|
|
export type ChecksumPolicy = 'auto' | 'required' | 'if-available' | 'disabled'
|
|
|
|
export async function run() {
|
|
let version = core.getInput('version')
|
|
const versionFile = core.getInput('version-file')
|
|
|
|
if (versionFile) {
|
|
if (version && version !== 'latest') {
|
|
core.warning(
|
|
`Both 'version' and 'version-file' inputs are specified, only 'version' will be used.`
|
|
)
|
|
} else {
|
|
version = getVersionFromToolVersionsFile(versionFile)
|
|
core.info(`Resolved Helm version '${version}' from '${versionFile}'`)
|
|
}
|
|
}
|
|
|
|
if (!version) {
|
|
version = 'latest'
|
|
}
|
|
|
|
const downloadBaseURL = core.getInput('downloadBaseURL', {required: false})
|
|
const downloadBaseURLFallback = core.getInput('downloadBaseURLFallback', {
|
|
required: false
|
|
})
|
|
const checksumPolicy = getChecksumPolicy(
|
|
core.getInput('checksum-policy', {required: false})
|
|
)
|
|
|
|
if (version.toLocaleLowerCase() === 'latest') {
|
|
// Only an explicit 'false' turns the fallback off, matching the
|
|
// input's default.
|
|
const fallbackToDefault =
|
|
core.getInput('latest-fallback').toLowerCase() !== 'false'
|
|
version = await getLatestHelmVersion(fallbackToDefault)
|
|
} else if (isMajorMinorShaped(version)) {
|
|
try {
|
|
version = await resolveLatestPatchVersion(downloadBaseURL, version)
|
|
} catch (error) {
|
|
if (!downloadBaseURLFallback) {
|
|
throw error
|
|
}
|
|
core.warning(
|
|
`Unable to resolve the latest Helm patch from '${downloadBaseURL}': ${error instanceof Error ? error.message : String(error)}. Trying fallback '${downloadBaseURLFallback}'`
|
|
)
|
|
version = await resolveLatestPatchVersion(
|
|
downloadBaseURLFallback,
|
|
version
|
|
)
|
|
}
|
|
core.info(`Resolved latest patch Helm version to '${version}'`)
|
|
} else if (version[0] !== 'v') {
|
|
version = getValidVersion(version)
|
|
core.info(`Normalized Helm version to '${version}'`)
|
|
}
|
|
|
|
core.startGroup(`Installing ${version}`)
|
|
const cachedPath = await downloadHelm(
|
|
downloadBaseURL,
|
|
version,
|
|
downloadBaseURLFallback,
|
|
checksumPolicy
|
|
)
|
|
core.endGroup()
|
|
|
|
try {
|
|
if (!process.env['PATH']?.startsWith(path.dirname(cachedPath))) {
|
|
core.addPath(path.dirname(cachedPath))
|
|
}
|
|
} catch {
|
|
//do nothing, set as output variable
|
|
}
|
|
|
|
core.info(`Helm tool version '${version}' has been cached at ${cachedPath}`)
|
|
core.setOutput('helm-path', cachedPath)
|
|
}
|
|
|
|
// Prefixes version with v
|
|
export function getValidVersion(version: string): string {
|
|
return 'v' + version
|
|
}
|
|
|
|
export function getChecksumPolicy(value: string): ChecksumPolicy {
|
|
const policy = value.trim().toLowerCase() || 'auto'
|
|
if (
|
|
policy !== 'auto' &&
|
|
policy !== 'required' &&
|
|
policy !== 'if-available' &&
|
|
policy !== 'disabled'
|
|
) {
|
|
throw new Error(
|
|
`Invalid checksum-policy '${value}'. Expected auto, required, if-available, or disabled`
|
|
)
|
|
}
|
|
return policy
|
|
}
|
|
|
|
// Matches a complete semantic version (major.minor.patch with optional
|
|
// pre-release / build metadata). This is the official regex suggested at
|
|
// https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string
|
|
// with an added optional leading 'v' to accept Helm-style tags (e.g. 'v3.14.0').
|
|
const semVerShape =
|
|
/^v?(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/
|
|
|
|
// Returns true when version looks like a semantic version
|
|
export function isSemVerShaped(version: string): boolean {
|
|
return semVerShape.test(version)
|
|
}
|
|
|
|
// Matches a major.minor version with an optional leading 'v' and either no
|
|
// patch component or a wildcard patch ('.x' / '.*'), e.g. '3.14', 'v3.14',
|
|
// '3.14.x', 'v3.14.*'.
|
|
const majorMinorShape = /^v?\d+\.\d+(?:\.[x*])?$/
|
|
|
|
// Returns true when version is a major.minor value (optionally with a wildcard
|
|
// patch such as '.x' or '.*')
|
|
export function isMajorMinorShaped(version: string): boolean {
|
|
return majorMinorShape.test(version)
|
|
}
|
|
|
|
// Reads a .tool-versions file and returns the helm version declared in it
|
|
export function getVersionFromToolVersionsFile(filePath: string): string {
|
|
if (!fs.existsSync(filePath)) {
|
|
throw new Error(`The version-file '${filePath}' does not exist`)
|
|
}
|
|
const content = fs.readFileSync(filePath, 'utf8')
|
|
const version = parseToolVersions(content)
|
|
if (!version) {
|
|
throw new Error(`No helm version found in '${filePath}'`)
|
|
}
|
|
if (!isSemVerShaped(version) && !isMajorMinorShaped(version)) {
|
|
throw new Error(
|
|
`The helm version '${version}' in '${filePath}' is not valid. Provide a full version (e.g. '3.14.0') or a major.minor version (e.g. '3.14' or '3.14.x')`
|
|
)
|
|
}
|
|
return version
|
|
}
|
|
|
|
// Parses .tool-versions content (asdf/mise format) and returns the first
|
|
// helm version, or an empty string when none is declared. Lines look like
|
|
// `helm 3.14.0`; comments (#) and blank lines are ignored.
|
|
export function parseToolVersions(content: string): string {
|
|
for (const line of content.split(/\r?\n/)) {
|
|
const trimmed = line.trim()
|
|
if (!trimmed || trimmed.startsWith('#')) {
|
|
continue
|
|
}
|
|
const [tool, version] = trimmed.split(/\s+/)
|
|
if (tool === helmToolName && version) {
|
|
return version
|
|
}
|
|
}
|
|
return ''
|
|
}
|
|
|
|
const latestVersionURL = 'https://get.helm.sh/helm-latest-version'
|
|
|
|
// Number of attempts made to fetch the latest version before giving up, and
|
|
// the wait before the second attempt (each further wait doubles the previous).
|
|
const latestVersionAttempts = 3
|
|
const latestVersionRetryDelayMs = 1000
|
|
|
|
// Fetches the latest helm version. A failed request or a non-2xx response is
|
|
// retried with a short backoff, so a single transient failure does not decide
|
|
// the outcome. Throws the last error once every attempt has failed.
|
|
export async function fetchLatestHelmVersion(): Promise<string> {
|
|
let delayMs = latestVersionRetryDelayMs
|
|
for (let attempt = 1; ; attempt++) {
|
|
try {
|
|
const response = await fetch(latestVersionURL)
|
|
if (!response.ok) {
|
|
// The body is never read, so cancel it to release the connection
|
|
// before the next attempt.
|
|
await response.body?.cancel()
|
|
throw new Error(
|
|
`Unexpected HTTP ${response.status} from ${latestVersionURL}`
|
|
)
|
|
}
|
|
return (await response.text()).trim()
|
|
} catch (err) {
|
|
if (attempt >= latestVersionAttempts) {
|
|
throw err
|
|
}
|
|
core.info(
|
|
`Attempt ${attempt} of ${latestVersionAttempts} to fetch the latest Helm version failed: ${err instanceof Error ? err.message : String(err)}. Retrying in ${delayMs}ms`
|
|
)
|
|
await new Promise((resolve) => setTimeout(resolve, delayMs))
|
|
delayMs *= 2
|
|
}
|
|
}
|
|
}
|
|
|
|
// Gets the latest helm version. When it cannot be determined, returns the
|
|
// built-in default version with a warning, or throws when fallbackToDefault
|
|
// is off. The default version can be a major behind what 'latest' resolves
|
|
// to, so the warning names the input that turns the fallback off.
|
|
export async function getLatestHelmVersion(
|
|
fallbackToDefault = true
|
|
): Promise<string> {
|
|
try {
|
|
return await fetchLatestHelmVersion()
|
|
} catch (err) {
|
|
const message = err instanceof Error ? err.message : String(err)
|
|
if (!fallbackToDefault) {
|
|
throw new Error(
|
|
`Unable to determine the latest Helm version: ${message}. Set 'latest-fallback' to 'true' to install the default version ${stableHelmVersion} instead, or request a specific version`
|
|
)
|
|
}
|
|
core.warning(
|
|
`Error while fetching latest Helm release: ${message}. Using default version ${stableHelmVersion}. Set 'latest-fallback' to 'false' to fail the step instead`
|
|
)
|
|
return stableHelmVersion
|
|
}
|
|
}
|
|
|
|
// Number of consecutive missing patches to probe before concluding the walk,
|
|
// and an upper bound to keep resolution from running unbounded.
|
|
const patchLookahead = 3
|
|
const maxPatch = 100
|
|
|
|
// Sends a HEAD request for the given version's download URL. Returns true when
|
|
// the artifact exists (2xx) and false only when it is definitively absent
|
|
// (404). Any other status (403/405/429/5xx, ...) and genuine network errors are
|
|
// thrown, so transient failures, rate-limiting, or a host that disallows HEAD
|
|
// are never mistaken for a missing patch.
|
|
export async function helmPatchExists(
|
|
baseURL: string,
|
|
version: string
|
|
): Promise<boolean> {
|
|
const url = getHelmDownloadURL(baseURL, version)
|
|
const response = await fetch(url, {method: 'HEAD'})
|
|
if (response.ok) {
|
|
return true
|
|
}
|
|
if (response.status === 404) {
|
|
return false
|
|
}
|
|
throw new Error(
|
|
`Unexpected HTTP ${response.status} while checking for Helm artifact at ${url}`
|
|
)
|
|
}
|
|
|
|
// Attempts to resolve the latest patch in a single request via the Azure Blob
|
|
// container-listing API that backs get.helm.sh. Returns the newest stable patch
|
|
// version, or null when the host does not support listing (any non-listing
|
|
// response, empty result, or error) so the caller can fall back to probing.
|
|
// Only 'major.minor.patch-<platform>' names are matched, so prereleases and
|
|
// sidecar files (.sha256, ...) are ignored.
|
|
export async function resolveLatestPatchViaListing(
|
|
baseURL: string,
|
|
major: string,
|
|
minor: string
|
|
): Promise<string | null> {
|
|
let body: string
|
|
try {
|
|
const listURL = new URL(baseURL)
|
|
listURL.searchParams.set('restype', 'container')
|
|
listURL.searchParams.set('comp', 'list')
|
|
listURL.searchParams.set('prefix', `helm-v${major}.${minor}.`)
|
|
const response = await fetch(listURL.toString())
|
|
if (!response.ok) {
|
|
return null
|
|
}
|
|
body = await response.text()
|
|
} catch {
|
|
return null
|
|
}
|
|
|
|
if (!body.includes('<EnumerationResults')) {
|
|
return null
|
|
}
|
|
|
|
const patchPattern = new RegExp(
|
|
`helm-v${major}\\.${minor}\\.(\\d+)-(?:darwin|linux|windows)`,
|
|
'g'
|
|
)
|
|
let latestPatch = -1
|
|
for (const match of body.matchAll(patchPattern)) {
|
|
const patch = Number(match[1])
|
|
if (patch > latestPatch) {
|
|
latestPatch = patch
|
|
}
|
|
}
|
|
|
|
if (latestPatch < 0) {
|
|
return null
|
|
}
|
|
return `v${major}.${minor}.${latestPatch}`
|
|
}
|
|
|
|
// Resolves a major.minor value (e.g. '3.14' or 'v3.14') to the newest available
|
|
// patch (e.g. 'v3.14.4'). Fast path: a single container-listing request (which
|
|
// get.helm.sh supports). When the host does not support listing, it falls back
|
|
// to probing the download host for sequential patches. Only 'major.minor.n'
|
|
// artifacts are considered, so prereleases are never selected.
|
|
export async function resolveLatestPatchVersion(
|
|
baseURL: string,
|
|
version: string
|
|
): Promise<string> {
|
|
const [major, minor] = (
|
|
version[0] === 'v' ? version.slice(1) : version
|
|
).split('.')
|
|
|
|
const listed = await resolveLatestPatchViaListing(baseURL, major, minor)
|
|
if (listed) {
|
|
return listed
|
|
}
|
|
|
|
if (!(await helmPatchExists(baseURL, `v${major}.${minor}.0`))) {
|
|
throw new Error(`No Helm releases found for ${major}.${minor}`)
|
|
}
|
|
|
|
let latestPatch = 0
|
|
let consecutiveMisses = 0
|
|
for (
|
|
let patch = 1;
|
|
patch <= maxPatch && consecutiveMisses < patchLookahead;
|
|
patch++
|
|
) {
|
|
if (await helmPatchExists(baseURL, `v${major}.${minor}.${patch}`)) {
|
|
latestPatch = patch
|
|
consecutiveMisses = 0
|
|
} else {
|
|
consecutiveMisses++
|
|
}
|
|
}
|
|
|
|
// The look-ahead is what should end the walk. Exhausting maxPatch without a
|
|
// trailing run of misses means the host answered 200 for every probe (e.g. a
|
|
// catch-all mirror), so the resolved version cannot be trusted.
|
|
if (consecutiveMisses < patchLookahead) {
|
|
throw new Error(
|
|
`Unable to resolve latest patch for ${major}.${minor} (exceeded ${maxPatch} probes)`
|
|
)
|
|
}
|
|
|
|
return `v${major}.${minor}.${latestPatch}`
|
|
}
|
|
|
|
export function getArch(): string {
|
|
return os.arch() === 'x64' ? 'amd64' : os.arch()
|
|
}
|
|
|
|
export function getPlatform(): string {
|
|
return os.platform() === 'win32' ? 'windows' : os.platform()
|
|
}
|
|
|
|
export function getArchiveExtension(): string {
|
|
return os.platform() === 'win32' ? 'zip' : 'tar.gz'
|
|
}
|
|
|
|
export function getExecutableExtension(): string {
|
|
return os.platform() === 'win32' ? '.exe' : ''
|
|
}
|
|
|
|
export function getHelmDownloadURL(baseURL: string, version: string): string {
|
|
const urlPath = `helm-${version}-${getPlatform()}-${getArch()}.${getArchiveExtension()}`
|
|
// Ensure the base ends with '/' so a subpath mirror (e.g.
|
|
// 'https://example/kubernetes/helm') is preserved; otherwise URL resolution
|
|
// replaces the last path segment and points at the wrong location.
|
|
const base = baseURL.endsWith('/') ? baseURL : `${baseURL}/`
|
|
const url = new URL(urlPath, base)
|
|
return url.toString()
|
|
}
|
|
|
|
export async function downloadAndVerifyHelm(
|
|
baseURL: string,
|
|
version: string,
|
|
policy: ChecksumPolicy = 'auto'
|
|
): Promise<string> {
|
|
const downloadURL = getHelmDownloadURL(baseURL, version)
|
|
const effectivePolicy = resolveChecksumPolicy(policy)
|
|
|
|
if (effectivePolicy === 'disabled') {
|
|
core.warning(
|
|
`Checksum verification is disabled for Helm downloads from '${baseURL}'`
|
|
)
|
|
return toolCache.downloadTool(downloadURL)
|
|
}
|
|
|
|
let checksum: string | undefined
|
|
try {
|
|
const checksumPath = await toolCache.downloadTool(`${downloadURL}.sha256`)
|
|
checksum = fs.readFileSync(checksumPath, 'utf8').trim()
|
|
} catch (error) {
|
|
if (
|
|
effectivePolicy === 'if-available' &&
|
|
isChecksumNotFoundError(error)
|
|
) {
|
|
core.warning(
|
|
`No SHA-256 checksum is available for ${downloadURL}; continuing without verification. Set checksum-policy to 'required' to fail instead.`
|
|
)
|
|
return toolCache.downloadTool(downloadURL)
|
|
}
|
|
throw error
|
|
}
|
|
|
|
if (!/^[a-fA-F0-9]{64}$/.test(checksum)) {
|
|
throw new Error(`Invalid SHA-256 checksum from ${downloadURL}.sha256`)
|
|
}
|
|
|
|
const archivePath = await toolCache.downloadTool(downloadURL)
|
|
const hash = createHash('sha256')
|
|
await new Promise<void>((resolve, reject) => {
|
|
const archive = fs.createReadStream(archivePath)
|
|
archive.on('data', (chunk) => hash.update(chunk))
|
|
archive.on('error', reject)
|
|
archive.on('end', resolve)
|
|
})
|
|
const actual = hash.digest('hex')
|
|
if (actual.toLowerCase() !== checksum.toLowerCase()) {
|
|
throw new Error(`SHA-256 checksum mismatch for ${downloadURL}`)
|
|
}
|
|
|
|
return archivePath
|
|
}
|
|
|
|
export function resolveChecksumPolicy(
|
|
policy: ChecksumPolicy
|
|
): Exclude<ChecksumPolicy, 'auto'> {
|
|
return policy === 'auto' ? 'if-available' : policy
|
|
}
|
|
|
|
function isChecksumNotFoundError(error: unknown): boolean {
|
|
return (
|
|
error instanceof toolCache.HTTPError &&
|
|
(error.httpStatusCode === 404 || error.httpStatusCode === 410)
|
|
)
|
|
}
|
|
|
|
export async function downloadHelm(
|
|
baseURL: string,
|
|
version: string,
|
|
fallbackBaseURL?: string,
|
|
checksumPolicy: ChecksumPolicy = 'auto'
|
|
): Promise<string> {
|
|
let cachedToolpath = toolCache.find(helmToolName, version)
|
|
if (cachedToolpath) {
|
|
core.info(`Restoring '${version}' from cache`)
|
|
} else {
|
|
core.info(`Downloading '${version}' from '${baseURL}'`)
|
|
let helmDownloadPath
|
|
try {
|
|
helmDownloadPath = await downloadAndVerifyHelm(
|
|
baseURL,
|
|
version,
|
|
checksumPolicy
|
|
)
|
|
} catch (error) {
|
|
if (fallbackBaseURL) {
|
|
core.warning(
|
|
`Unable to download and verify Helm from '${baseURL}': ${error instanceof Error ? error.message : String(error)}. Trying fallback '${fallbackBaseURL}'`
|
|
)
|
|
try {
|
|
helmDownloadPath = await downloadAndVerifyHelm(
|
|
fallbackBaseURL,
|
|
version,
|
|
checksumPolicy
|
|
)
|
|
} catch (fallbackError) {
|
|
throw new Error(
|
|
`Failed to download and verify Helm from '${baseURL}' and fallback '${fallbackBaseURL}': ${fallbackError instanceof Error ? fallbackError.message : String(fallbackError)}`
|
|
)
|
|
}
|
|
} else {
|
|
throw new Error(
|
|
`Failed to download and verify Helm from location ${getHelmDownloadURL(
|
|
baseURL,
|
|
version
|
|
)}: ${error instanceof Error ? error.message : String(error)}`
|
|
)
|
|
}
|
|
}
|
|
|
|
if (!helmDownloadPath) {
|
|
throw new Error(
|
|
`Failed to download and verify Helm version '${version}'`
|
|
)
|
|
}
|
|
|
|
fs.chmodSync(helmDownloadPath, '755')
|
|
const extractedPath =
|
|
getPlatform() === 'windows'
|
|
? await toolCache.extractZip(helmDownloadPath)
|
|
: await toolCache.extractTar(helmDownloadPath)
|
|
|
|
cachedToolpath = await toolCache.cacheDir(
|
|
extractedPath,
|
|
helmToolName,
|
|
version
|
|
)
|
|
}
|
|
|
|
const helmpath = findHelm(cachedToolpath)
|
|
if (!helmpath) {
|
|
throw new Error(
|
|
util.format('Helm executable not found in path', cachedToolpath)
|
|
)
|
|
}
|
|
|
|
fs.chmodSync(helmpath, '755')
|
|
return helmpath
|
|
}
|
|
|
|
export function findHelm(rootFolder: string): string {
|
|
fs.chmodSync(rootFolder, '755')
|
|
let filelist: string[] = []
|
|
walkSync(rootFolder, filelist, helmToolName + getExecutableExtension())
|
|
if (!filelist || filelist.length == 0) {
|
|
throw new Error(
|
|
util.format('Helm executable not found in path', rootFolder)
|
|
)
|
|
} else {
|
|
return filelist[0]
|
|
}
|
|
}
|
|
|
|
export function walkSync(dir, filelist, fileToFind) {
|
|
const files = fs.readdirSync(dir)
|
|
filelist = filelist || []
|
|
files.forEach(function (file) {
|
|
if (fs.statSync(path.join(dir, file)).isDirectory()) {
|
|
filelist = walkSync(path.join(dir, file), filelist, fileToFind)
|
|
} else {
|
|
core.debug(file)
|
|
if (file == fileToFind) {
|
|
filelist.push(path.join(dir, file))
|
|
}
|
|
}
|
|
})
|
|
return filelist
|
|
}
|