Upload Docs to S3

The upload-docs.yml workflow publishes a repository's built documentation to the neulabs-docs-swamp S3 bucket whenever the docs/ folder changes on main.

Trigger

Event	Condition
Push to main	Only when files under docs/** change
Manual	workflow_dispatch — no conditions

Required GitHub variables

Variable	Value
AWS_DOCS_ROLE_TO_ASSUME	ARN of github-oidc-workflow-role (from CDK output)
AWS_REGION	eu-west-1

Both variables are set in the repository settings → Variables. The role ARN is printed as a CDK stack output when deploy-infra.yml runs.

What it does

1. Checks out the repository.
2. Assumes github-oidc-workflow-role via OIDC — no long-lived credentials are stored anywhere.
3. Verifies that a docs/ directory exists; aborts with an error if it does not.
4. Runs aws s3 sync docs/ s3://neulabs-docs-swamp/<repo-name>/ --delete, where <repo-name> is resolved automatically from github.event.repository.name.

The --delete flag removes any objects from S3 that no longer exist locally, keeping the bucket in sync with the current state of docs/.

Destination path

Each repository gets its own prefix inside the shared bucket:

s3://neulabs-docs-swamp/<repo-name>/

For example, a repository named my-service syncs to:

s3://neulabs-docs-swamp/my-service/

Permissions

The workflow requests only the minimum GitHub Actions permissions required for OIDC authentication:

permissions:
  id-token: write   # required to request an OIDC token
  contents: read    # required to checkout the repository

The github-oidc-workflow-role IAM role (provisioned by the CDK stack) grants S3 write access to neulabs-docs-swamp and nothing else.

Notes

• The workflow does not build the Docusaurus site. It syncs whatever is present in docs/ as-is. Run npm run build locally or in a prior CI step to generate static output before relying on this workflow for publishing built artifacts.
• If docs/ does not exist in the repository, the workflow exits with a non-zero status and the run is marked as failed.