CLI & Pytest Plugin Reference¶

← Home • Quick Start • AWS Setup • Architecture • CLI

Deployment steps demo (GIF)

One-time AWS setup flow using the CLI helpers (non-destructive unless DEMO_REAL=1 is set).

Deploying-phase capture:

Tip: If the GIF appears cached, hard refresh or bump the ?v= query.

CLI Flags (publish-allure)¶

Flag	Description	Default / Source
`--bucket`	Target S3 bucket (required)	—
`--prefix`	Root reports prefix	`reports`
`--project`	Logical project name	(required)
`--branch`	Branch or stream	`GIT_BRANCH` or `main`
`--run-id`	Unique run identifier	`ALLURE_RUN_ID` or timestamp
`--results` / `--results-dir`	Input results directory	`ALLURE_RESULTS_DIR` / `allure-results`
`--report`	Output build directory	`ALLURE_REPORT_DIR` / `allure-report`
`--cloudfront`	CloudFront base URL (for final URLs)	`ALLURE_CLOUDFRONT`
`--ttl-days`	Tag objects with a TTL (days)	—
`--max-keep-runs`	Prune older run prefixes, keep newest N	—
`--summary-json PATH`	Emit machine JSON summary	—
`--context-url URL`	External link (PR / ticket)	`ALLURE_CONTEXT_URL`
`--meta KEY=VAL` (repeat)	Attach arbitrary metadata to manifest / runs index	—
`--s3-endpoint`	Custom S3 endpoint (LocalStack/minio)	`ALLURE_S3_ENDPOINT`
`--sse`	S3 server-side encryption (AES256 or aws:kms)	`ALLURE_S3_SSE`
`--sse-kms-key-id`	KMS Key when `--sse=aws:kms`	`ALLURE_S3_SSE_KMS_KEY_ID`
`--upload-workers`	Parallel upload workers (auto if unset)	auto
`--copy-workers`	Parallel copy workers for latest promotion	auto
`--archive-run`	Produce a compressed archive of the run	false
`--archive-format`	Archive format (`tar.gz` or `zip`)	`tar.gz`
`--verbose-summary`	Print extended summary lines	false
`--allow-duplicate-prefix-project`	Bypass guard if prefix == project	false
`--check`	Preflight validations only	false
`--dry-run`	Plan without uploading	false
`--version`	Show version and exit	—

Windows note: Paths are normalized internally; prefer forward slashes in config files to avoid escaping issues (e.g. use allure-results not allure\\results).

Pytest Plugin Options¶

Option	CLI Flag	Notes
`--allure-bucket`	`--bucket`	required
`--allure-prefix`	`--prefix`
`--allure-project`	`--project`	required
`--allure-branch`	`--branch`	auto from `GIT_BRANCH`
`--allure-run-id`	`--run-id`
`--allure-cloudfront`	`--cloudfront`
`--allure-ttl-days`	`--ttl-days`
`--allure-max-keep-runs`	`--max-keep-runs`
`--allure-summary-json`	`--summary-json`
`--allure-context-url`	`--context-url`
`--allure-check`	`--check`
`--allure-dry-run`	`--dry-run`

Exit Codes¶

Code	Meaning
0	Success / dry-run success
2	Preflight failure (missing results, allure binary, AWS access)
3	Upload or promote failure

Preflight Checks¶

Bucket reachable (HeadBucket / limited ListBucket)
allure-results present and not empty
Allure CLI available (or plugin generates via allure-pytest)
Java runtime present (the Allure CLI requires a JRE/JDK)

Quick verify:

java -version
allure --version

End-to-end dry preflight example:

publish-allure \
  --bucket my-allure-reports \
  --project demo \
  --branch main \
  --cloudfront https://reports.example.com \
  --check --dry-run

Summary JSON Schema (Example)¶

{
  "run_id": "20250929-101233",
  "run_prefix": "reports/demo/main/20250929-101233/",
  "latest_prefix": "reports/demo/main/latest/",
  "run_url": "https://reports.example.com/reports/demo/main/20250929-101233/",
  "latest_url": "https://reports.example.com/reports/demo/main/latest/",
  "file_count": 248,
  "total_bytes": 1048576,
  "context_url": "https://github.com/org/repo/pull/123"
}

Manifest Entry (Excerpt)¶

{
  "run_id": "20250929-101233",
  "time": 1759073700,
  "size": 1048576,
  "commit": "abc1234",
  "context_url": "https://github.com/org/repo/pull/123"
}

History & Two-Phase Latest¶

Copy latest/history locally (best effort)
Generate new static report
Upload run prefix
Upload to temp latest_tmp/
Copy into latest/ (or sync) + write LATEST_READY

Consumer polling tip: wait until latest/LATEST_READY exists (or HEAD on latest/index.html returns 200 shortly after the marker appears) before aggregating widget JSON to avoid mixing versions.

LocalStack Example¶

awslocal s3 mb s3://local-bucket || true
publish-allure \
  --bucket local-bucket \
  --project demo \
  --branch main \
  --s3-endpoint http://localhost:4566 \
  --cloudfront https://localhost.localdomain \
  --dry-run

Common Pitfalls¶

Issue	Explanation	Fix
Empty report	No test results produced	Ensure tests executed with allure plugin
No latest history	First run or fetch failed	Ignore first-time or check IAM permission
Stale cache	CDN caching index	Confirm index `Cache-Control: no-cache`
Missing types	Some unusual MIME	Open an issue with sample filename
HTTP 301 redirect	Region mismatch	`aws s3api get-bucket-location`
CORS fetch failure	Missing CORS rules	Apply minimal GET/HEAD CORS if embedding
Windows paths	Backslashes in config path	Use forward slashes / rely on normalization

Auto Configuration (YAML or TOML)¶

Instead of repeatedly passing flags you can create a config file in the project root.

Discovery order (first match wins):

allurehost.toml
.allurehost.toml
allure-host.yml
allure-host.yaml
.allure-host.yml
.allure-host.yaml
application.yml (fallback)

Example allurehost.toml:

bucket = "my-allure-reports"
prefix = "reports"
project = "payments"
branch = "main"        # optional, else auto from GIT_BRANCH or 'main'
cloudfront = "https://reports.example.com"
ttl_days = 30
max_keep_runs = 10

Then run:

publish-allure --dry-run

Or with pytest (flags only for overrides):

pytest --allure-dry-run --alluredir=allure-results

Precedence per field (highest first): CLI flag > Env var (e.g. ALLURE_BUCKET) > Config file value > Built‑in default.

Metadata (`--meta`)¶

Attach arbitrary key/value pairs to enrich the manifest and future dashboards:

publish-allure ... --meta jira=PAY-123 --meta env=staging --meta commit=$(git rev-parse --short HEAD)

Keys are lower‑cased and hyphens converted to underscores. They appear in the JSON manifest entries and can drive external tooling.

Encryption¶

If your bucket enforces SSE-KMS:

publish-allure ... --sse aws:kms --sse-kms-key-id arn:aws:kms:REGION:ACCOUNT:key/KEY_ID

Or enable basic AES256:

publish-allure ... --sse AES256

Parallelism¶

Tune performance for large reports (many screenshots):

publish-allure ... --upload-workers 16 --copy-workers 8

Leave unset to auto‑size based on CPU.

Archiving¶

Produce a compressed artifact of the generated run (useful for long‑term cold storage or attaching to build artifacts):

publish-allure ... --archive-run --archive-format zip

Archive is uploaded alongside the run prefix with naming convention <run_id>.tar.gz (or .zip).

Guard: Duplicate Prefix/Project¶

To prevent accidental redundant S3 paths, identical --prefix and --project are blocked. Override only if you truly intend that layout:

publish-allure ... --allow-duplicate-prefix-project

Verbose Summary¶

Last updated: 2025-10-08

Add --verbose-summary to print CDN root mappings, manifest key, encryption info, and metadata keys.