openapi: Add openapi/upload composite action#208
Conversation
Foundation for the OpenAPI-specs-to-S3 rollout (RFC elastic/docs-eng-team#634, tracked by elastic/docs-eng-team#640). Uploads an already-linted, already-bundled spec to S3 via OIDC, using the same role-derivation scheme as aws/auth and the bucket/role scoping provisioned in elastic/docs-infra#339. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Replace the path-traversal validator on spec-name/version with the single-segment allowlist regex already used for artifact-name in changelog/bundle-upload — the path validator only rejected a leading "/" and literal "..", so an embedded slash (e.g. spec-name: foo/bar) silently produced a nested S3 key the layout doesn't intend. Also collapse the duplicated yaml/yml case branches (ext is now derived from the path suffix) and trim README prose that just restated the generated input descriptions. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
| <!-- Generated by https://github.com/reakaleek/gh-action-readme --> | ||
| # <!--name-->OpenAPI upload<!--/name--> | ||
| <!--description--> | ||
| Uploads an already-linted, already-bundled OpenAPI spec to S3 (elastic-docs-openapi-specs) via OIDC. Does not lint and does not bundle — the consumer workflow is responsible for both before calling this action. Part of the RFC for publishing OpenAPI specs to S3 (elastic/docs-eng-team#634). |
There was a problem hiding this comment.
At what point should we catch non-linted or non-bundled specs? Does the process rely entirely on trust and correct behaviour prior to upload?
There was a problem hiding this comment.
It's a good point. Thank you.. I was thinking of adding a step here that runs the lint right before upload.
But this would depend on #207 to get merged first.
I would definitely handle it as follow-up.
There was a problem hiding this comment.
In general, these actions were meant to be part of a broader reusable workflow that orechestrates the usage of these actions.
But i'm starting to think that every repository generates the OAS so differently that it's not feasible to create a reusable workflow from the get go..
Maybe in a refactoring follow-up after learning how it works today.
Drop the RFC/issue reference and the redundant bucket name (already the s3-bucket input's default) from the description. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Mirror validate_path with a validate_segment helper instead of bare if-blocks, so the two validation shapes (path-like vs. single-segment) read the same way at the call sites. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
cotti
left a comment
cotti
left a comment
There was a problem hiding this comment.
LGTM mostly, just want to confirm one point
| S3_PREFIX: ${{ inputs.s3-prefix }} | ||
| VERSION: ${{ inputs.version }} | ||
| run: | | ||
| validate_path() { |
There was a problem hiding this comment.
It's missing a symlink check for this. It could have a
if [[ -L "$SPEC_PATH" ]]; then
echo "::error::spec-path must not be a symlink: ${SPEC_PATH}"; exit 1
fi
or maybe reuse the Reject symlink step on docs-deploy?
3 participants
Closes https://github.com/elastic/docs-eng-team/issues/640
What
Adds
openapi/upload, a composite action that uploads an already-linted, already-bundled OpenAPI spec to S3 via OIDC.Why
Foundation work for the OpenAPI-specs-to-S3 rollout — RFC elastic/docs-eng-team#634, tracked by elastic/docs-eng-team#640. All per-repo adoption is blocked on this action existing.
How
changelog/uploadandchangelog/bundle-upload: an inline bash validation step (reject absolute paths,.., newlines), thenaws/auth@v1with a newelastic-docs-openapi-role-name prefix, thenaws s3 cp --checksum-algorithm SHA256with the correct content-type.elastic-docs-openapi-specs), account, region, and role-prefix defaults match what's provisioned inelastic/docs-infra#339.<s3-prefix>/<version>/<spec-name>.<ext>, defaulting prefix to${{ github.repository }}(required — IAM only grantss3:PutObjectunder that prefix) and version to the triggering branch, overridable for repos likeelastic/cloudwith non-standard branch names.openapi/lintis a separate action; bundling e.g. viaredocly bundlehappens in the consumer's own workflow step). README documents the two-workflow (PR lint / publish-on-merge) integration pattern from the RFC.Test plan
pre-commit run—check-yaml,action-readmepass; README tables regenerate with no drift.yaml/.json), absolute path,.., newline, emptyspec-name, bad extension, missing file — all pass/fail as expecteds3://elastic-docs-openapi-specs/elastic/kibana/main/kibana.yaml)elastic/docs-infra#339(bucket + OIDC roles) mergingNotes
Acceptance criteria in elastic/docs-eng-team#640 mention bundling inside this action; per discussion, bundling was moved to the consumer's responsibility instead, so this action only validates, authenticates, and uploads.