backblaze-labs/Backblaze B2 Cloud Storage Action
Upload, download, sync, copy, and manage Backblaze B2 Cloud Storage from GitHub Actions workflows.
View on GitHubTrust Signals
- Scorecard Score
- not yet scored
- Maintenance Recency
- Activelast commit Jul 8, 2026
- License
- MIT
Pinned Snippet
uses: backblaze-labs/b2-action@1678a4d7217a31606ec58d046be5ad189e1ee5cc # v1.1.0tags can be moved; commit SHAs can't. why a SHA?
Inputs
| name | description | required | default |
|---|---|---|---|
| action | One of: upload | download | sync | copy | delete | presign | list | hide | unhide | verify | retention | head | purge | yes | — |
| application-key-id | B2 application key ID. If unset, falls back to the $B2_APPLICATION_KEY_ID env var. | no | — |
| application-key | B2 application key. If unset, falls back to the $B2_APPLICATION_KEY env var. | no | — |
| bucket | Target bucket name (the destination bucket for copy). | yes | — |
| source-bucket | Source bucket for cross-bucket copy. Defaults to `bucket`. | no | — |
| source | Command-dependent. upload/sync (up): local path or glob. download/sync (down)/copy/delete/presign/list/hide/unhide/verify/retention/head/purge: B2 file name or prefix. Prefix downloads reject keys with empty, `.`, `..`, or control-character path segments. For whole-bucket purge, omit source or set `/` and set allow-bucket-purge: true. | no | — |
| destination | Command-dependent. upload/sync (up): B2 file name or prefix; SDK/B2 key validation errors are surfaced rather than silently rewriting `/` characters. download/sync (down): local path or directory. copy: destination B2 file name. verify: local file to compare against the remote SHA-1. | no | — |
| include | Comma-separated globs to include (upload). Patterns are anchored to source. | no | — |
| exclude | Comma-separated globs to exclude (upload). Defaults exclude .git/**. | no | .git/** |
| concurrency | Parallel parts for a large upload, or parallel files for a glob/sync. Must be a positive decimal integer. Default 4. | no | 4 |
| part-size | Multipart part size in bytes. Must be a positive decimal integer. Defaults to the SDK-recommended size. | no | — |
| resume | Reserved. Accepted for forward compatibility but currently not honored: the action uploads through a streaming source that the SDK cannot slice for resume. Set, but expect a full re-upload on retry. | no | true |
| content-type | Content-Type for uploads. Defaults to "b2/x-auto" (B2 auto-detects). | no | — |
| file-info | Custom upload fileInfo metadata as newline- or simple comma-separated key=value pairs. Use newline-separated entries when values contain commas. Keys are normalized to lowercase, may contain letters, digits, and B2-supported special characters (-_.`~!#$%^&*'|+), cannot start with b2-, and must fit B2 fileInfo limits. Use cache-control/content-disposition/content-language/expires for reserved b2-* response headers. | no | — |
| cache-control | Cache-Control response header to store with uploaded files. | no | — |
| content-disposition | Content-Disposition response header to store with uploaded files. | no | — |
| content-language | Content-Language response header to store with uploaded files. | no | — |
| expires | Expires response header to store with uploaded files. | no | — |
| preserve-mtime | Store each uploaded file's local modification time as B2 src_last_modified_millis. Default false. | no | false |
| dry-run | Preview what would happen without executing (sync/delete/purge). Default false. | no | false |
| allow-bucket-purge | Permit `purge` to target the entire bucket when `source` is empty or `/`. Default false; ignored by other actions. | no | false |
| presign-ttl | Presigned URL TTL in seconds (presign action). Must be a positive decimal integer. Default 3600. | no | 3600 |
| endpoint | Override the B2 realm endpoint. Leave empty for production. | no | — |
| fail-on-empty | Fail the action if an upload glob matches zero files (default true). | no | true |
| sse | Server-side encryption: "B2" (SSE-B2) or "C:<base64-32-byte-key>" (SSE-C). SSE-C keys must use canonical base64 and decode to exactly 32 bytes. | no | — |
| compare-mode | Sync comparison: modtime | size | none. Default modtime. | no | modtime |
| keep-mode | Sync deletion policy for orphans: no-delete | delete | keep-days. Default no-delete. | no | no-delete |
| direction | Sync direction: auto | up (local→B2) | down (B2→local). Default auto. | no | auto |
| max-results | Maximum number of files returned by `list`. Must be a positive decimal integer. Default 1000. | no | 1000 |
| expected-sha1 | Expected 40-character hexadecimal SHA-1 digest for `verify`; malformed values fail before comparison. If unset, the SHA-1 is computed from `destination` (a local file). Non-comparable remote SHA-1 headers such as `none` or `unverified:<sha1>` publish `verified=false` outputs before failing the step. | no | — |
| retention-mode | Object Lock retention mode for `retention`: compliance | governance | none. | no | — |
| retention-until | ISO 8601 timestamp until which the file is retained (required when retention-mode is compliance/governance). | no | — |
| legal-hold | Legal hold status for `retention`: on | off. | no | — |
| bypass-governance | Allow governance-mode retention bypass for retention changes and delete/purge operations (requires bypassGovernance capability). | no | false |
Outputs
| name | description |
|---|---|
| file-id | B2 file ID of a single-file op (upload, copy, hide, retention, head). For `unhide`, set only when a hide marker is removed and identifies that removed marker. |
| file-name | B2 file name (path) of a single-file op. |
| content-sha1 | SHA-1 hex digest when B2 provides a whole-file digest; omitted when unavailable, including multipart objects. |
| bytes-transferred | Total bytes uploaded/downloaded/copied/synced. Head emits 0. |
| file-count | Aggregate count of files matched or processed, including skipped sync entries and dry-run delete/purge matches. Prefer verb-specific count outputs when available. |
| files-uploaded | Number of files uploaded (upload glob / sync up). |
| files-downloaded | Number of files downloaded (download prefix / sync down). |
| files-deleted | Number of files deleted (delete / purge / sync). |
| files-listed | Number of files returned by `list` or prefix `presign`. |
| presigned-url | Presigned download URL (presign action). This is the only structured output that carries the live presigned URL. |
| verified | true/false: whether `verify` succeeded. |
| remote-sha1 | Normalized comparable remote SHA-1 from `verify`, raw non-comparable B2 value such as `none` or `unverified:<sha1>`, or empty when B2 does not expose one. |
| local-sha1 | Local file SHA-1 computed by `verify`. |
| summary-json | Complete JSON array with per-file details when the manifest fits within 256 KiB of UTF-8 JSON text. When exceeded, emits [] instead of changing shape or emitting a partial array. Credential-like fields are omitted by name for every command. For upload entries, fileInfo is SDK-returned metadata when available, otherwise canonical submitted metadata. For presign, entries omit live presigned URLs. |
| summary-json-truncated | Always-emitted true/false branch key; true when the full manifest exceeded the supported summary-json size cap. When true, file-count and verb-specific count outputs remain the authoritative totals. |
| summary-json-notice | Small JSON truncation notice emitted only when summary-json-truncated is true, with truncated, reason, totalCount, previewCount, and previewOutput fields. |
| summary-json-preview | Bounded partial JSON array emitted only when summary-json-truncated is true. Do not treat it as a complete manifest. Credential-like fields are omitted by name for every command. For presign, entries omit live presigned URLs. |
| retryable | Failure-path signal for classified SDK errors: true only when the action is safe to re-run automatically. |
| retry-after | Failure-path retry delay in seconds, clamped to 3600 and emitted only with retryable=true. |