Skip to content

openapi/upload: attach commit, repository, and branch as S3 metadata #273

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
reakaleek wants to merge 1 commit into
base: main
Choose a base branch
from
Open

openapi/upload: attach commit, repository, and branch as S3 metadata #273

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
12 changes: 9 additions & 3 deletions openapi/upload/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,8 @@ Uploads an already-linted, already-bundled OpenAPI spec to S3 via OIDC. Does not
| `s3-bucket` | Target S3 bucket. Only override if a different bucket has been provisioned. | `false` | `elastic-docs-openapi-specs` |
| `s3-prefix` | Key prefix under the bucket. Defaults to "<org>/<repo>", which is also the prefix the OIDC role is scoped to write — only override within that same repo prefix, or the upload will be denied.<br> | `false` | `${{ github.repository }}` |
| `version` | Version segment of the key. Defaults to the triggering branch name. Override for repos whose branch names do not match the RFC convention (e.g. elastic/cloud, whose default branch is "master" and whose release branches are named "ECE-4.1").<br> | `false` | `${{ github.ref_name }}` |
| `branch` | Git branch that triggered the upload. Stored as S3 object metadata, not used in the object key. Defaults to the triggering branch name.<br> | `false` | `${{ github.ref_name }}` |
| `commit` | Full git commit SHA that produced the uploaded spec. | `false` | `${{ github.sha }}` |
| `aws-region` | The AWS region to use | `false` | `us-east-1` |
| `aws-account-id` | The AWS account ID. Only override if OIDC trust and IAM roles have been provisioned for the target account. | `false` | `197730964718` |
<!--/inputs-->
Expand Down Expand Up @@ -52,7 +54,8 @@ jobs:
- uses: elastic/docs-actions/openapi/upload@v1
with:
spec-path: openapi.yaml
# uploads to elastic/<repo>/<branch>/openapi.yaml
# uploads to s3://elastic-docs-openapi-specs/<org>/<repo>/<version>/openapi.yaml
# metadata: x-amz-meta-commit, x-amz-meta-repository, x-amz-meta-branch
```

**Multiple specs** (e.g. Kibana's stateful and serverless specs): add a separate publish job per spec, setting `spec-name` per job:
Expand All @@ -65,11 +68,14 @@ jobs:
# uploads to elastic/kibana/<branch>/kibana.yaml
```

**Non-standard branch names**: repos like `elastic/cloud` (default branch `master`, release branches named `ECE-4.1`) must set `version` explicitly:
**Non-standard branch names**: repos like `elastic/cloud` (default branch `master`, release branches named `ECE-4.1`) must set `version` explicitly. `branch` defaults to `github.ref_name` and is stored as object metadata, so it records the real git ref even when `version` differs:

```yaml
- uses: elastic/docs-actions/openapi/upload@v1
with:
spec-path: openapi.yaml
version: ${{ github.ref_name == 'master' && 'main' || github.ref_name }}
version: ${{ github.ref_name == 'master' && 'main' || startsWith(github.ref_name, 'ECE-') && replace(github.ref_name, 'ECE-', '') || github.ref_name }}
# branch defaults to github.ref_name — metadata records ECE-4.1, key uses 4.1
```

Each uploaded object sets S3 user metadata: `x-amz-meta-commit`, `x-amz-meta-repository` (same value as `s3-prefix`), and `x-amz-meta-branch` (same value as `branch`). Read these with `HeadObject` without parsing the object key.
31 changes: 31 additions & 0 deletions openapi/upload/action.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,14 @@ inputs:
(e.g. elastic/cloud, whose default branch is "master" and whose release
branches are named "ECE-4.1").
default: '${{ github.ref_name }}'
branch:
description: >
Git branch that triggered the upload. Stored as S3 object metadata, not
used in the object key. Defaults to the triggering branch name.
default: '${{ github.ref_name }}'
commit:
description: 'Full git commit SHA that produced the uploaded spec.'
default: '${{ github.sha }}'
aws-region:
description: 'The AWS region to use'
default: 'us-east-1'
Expand All @@ -45,6 +53,8 @@ runs:
SPEC_NAME: ${{ inputs.spec-name }}
S3_PREFIX: ${{ inputs.s3-prefix }}
VERSION: ${{ inputs.version }}
BRANCH: ${{ inputs.branch }}
COMMIT: ${{ inputs.commit }}
run: |
source "${GITHUB_ACTION_PATH}/../../scripts/validate-inputs.sh"

Expand All @@ -53,6 +63,24 @@ runs:
validate_segment "$SPEC_NAME" "spec-name"
validate_segment "$VERSION" "version"

if [[ -z "$BRANCH" ]]; then
echo "::error::branch must not be empty"
exit 1
fi
if [[ "$BRANCH" == *$'\n'* || "$BRANCH" == *$'\r'* ]]; then
echo "::error::branch must not contain newlines"
exit 1
fi
if [[ "$BRANCH" =~ [[:cntrl:]] ]]; then
echo "::error::branch must not contain control characters: ${BRANCH}"
exit 1
fi

if [[ ! "$COMMIT" =~ ^[0-9a-f]{40}$ ]]; then
echo "::error::commit must be a 40-character lowercase hex SHA: ${COMMIT}"
exit 1
fi

case "$SPEC_PATH" in
*.yaml|*.yml) content_type=application/yaml ;;
*.json) content_type=application/json ;;
Expand Down Expand Up @@ -92,9 +120,12 @@ runs:
S3_BUCKET: ${{ inputs.s3-bucket }}
S3_PREFIX: ${{ inputs.s3-prefix }}
VERSION: ${{ inputs.version }}
BRANCH: ${{ inputs.branch }}
COMMIT: ${{ inputs.commit }}
EXT: ${{ steps.resolve.outputs.ext }}
CONTENT_TYPE: ${{ steps.resolve.outputs.content-type }}
run: |
aws s3 cp --checksum-algorithm SHA256 --content-type "$CONTENT_TYPE" \
--metadata "commit=${COMMIT},repository=${S3_PREFIX},branch=${BRANCH}" \
"$SPEC_PATH" \
"s3://${S3_BUCKET}/${S3_PREFIX}/${VERSION}/${SPEC_NAME}.${EXT}"
Loading