Configure deployment

Configure deployments to Amazon S3, Azure Blob Storage, or Google Cloud Storage.

This configuration is only relevant when running hugo deploy. See details.

Top-level options

These settings control the overall behavior of the deployment process. This is the default configuration:

deployment:
  confirm: false
  dryRun: false
  force: false
  invalidateCDN: true
  matchers: null
  maxDeletes: 256
  order: null
  target: ''
  targets: null
  workers: 10

[deployment]
  confirm = false
  dryRun = false
  force = false
  invalidateCDN = true
  maxDeletes = 256
  target = ''
  workers = 10

{
   "deployment": {
      "confirm": false,
      "dryRun": false,
      "force": false,
      "invalidateCDN": true,
      "matchers": null,
      "maxDeletes": 256,
      "order": null,
      "target": "",
      "targets": null,
      "workers": 10
   }
}

confirm: (bool) Whether to prompt for confirmation before deploying. Default is false.
dryRun: (bool) Whether to simulate the deployment without any remote changes. Default is false.
force: (bool) Whether to re-upload all files. Default is false.
invalidateCDN: (bool) Whether to invalidate the CDN cache listed in the deployment target. Default is true.
maxDeletes: (int) The maximum number of files to delete, or -1 to disable. Default is 256.
matchers: ([]*Matcher) A slice of matchers.
order: ([]string) An ordered slice of regular expressions that determines upload priority (left to right). Files not matching any expression are uploaded last in an arbitrary order.
target: (string) The target deployment name. Defaults to the first target.
targets: ([]*Target) A slice of targets.
workers: (int) The number of concurrent workers to use when uploading files. Default is 10.

Targets

A target represents a deployment target such as “staging” or “production”.

cloudFrontDistributionID: (string) The CloudFront Distribution ID, applicable if you are using the Amazon Web Services CloudFront CDN. Hugo will invalidate the CDN when deploying this target.
exclude: (string) A glob pattern matching files to exclude when deploying to this target. Local files failing the include/exclude filters are not uploaded, and remote files failing these filters are not deleted.
googleCloudCDNOrigin: (string) The Google Cloud project and CDN origin to invalidate when deploying this target, specified as <project>/<origin>.
include: (string) A glob pattern matching files to include when deploying to this target. Local files failing the include/exclude filters are not uploaded, and remote files failing these filters are not deleted.
name: (string) An arbitrary name for this target.
stripIndexHTML: (bool) Whether to map files named <dir>/index.html to <dir> on the remote (except for the root index.html). This is useful for key-value cloud storage (e.g., Amazon S3, Google Cloud Storage, Azure Blob Storage) to align canonical URLs with object keys. Default is false.
url: (string) The destination URL for deployment.

Matchers

A Matcher represents a configuration to be applied to files whose paths match the specified pattern.

cacheControl: (string) The caching attributes to use when serving the blob. See details.
contentEncoding: (string) The encoding used for the blob’s content, if any. See details.
contentType: (string) The media type of the blob being written. See details.
force: (bool) Whether matching files should be re-uploaded. Useful when other route-determined metadata (e.g., contentType) has changed. Default is false.
gzip: (bool) Whether the file should be gzipped before upload. If so, the ContentEncoding field will automatically be set to gzip. Default is false.
pattern: (string) A regular expression used to match paths. Paths are converted to use forward slashes (/) before matching.

Destination URLs

Service	URL example
Amazon Simple Storage Service (S3)	`s3://my-bucket?region=us-west-1`
Azure Blob Storage	`azblob://my-container`
Google Cloud Storage (GCS)	`gs://my-bucket`

With Google Cloud Storage you can target a subdirectory:

gs://my-bucket?prefix=a/subdirectory

You can also to deploy to storage servers compatible with Amazon S3 such as:

For example, the url for a MinIO deployment target might resemble this:

s3://my-bucket?endpoint=https://my.minio.instance&awssdk=v2&use_path_style=true&disable_https=false

Example

deployment:
  matchers:
  - cacheControl: max-age=31536000, no-transform, public
    gzip: true
    pattern: '^.+\.(js|css|svg|ttf)$'
  - cacheControl: max-age=31536000, no-transform, public
    gzip: false
    pattern: '^.+\.(png|jpg)$'
  - contentType: application/xml
    gzip: true
    pattern: '^sitemap\.xml$'
  - gzip: true
    pattern: '^.+\.(html|xml|json)$'
  order:
  - .jpg$
  - .gif$
  targets:
  - cloudFrontDistributionID: E1234567890ABCDEF0
    exclude: '**.{heic,psd}'
    name: production
    url: s3://my_production_bucket?region=us-west-1
  - exclude: '**.{heic,psd}'
    name: staging
    url: s3://my_staging_bucket?region=us-west-1

[deployment]
  order = ['.jpg$', '.gif$']
  [[deployment.matchers]]
    cacheControl = 'max-age=31536000, no-transform, public'
    gzip = true
    pattern = '^.+\.(js|css|svg|ttf)$'
  [[deployment.matchers]]
    cacheControl = 'max-age=31536000, no-transform, public'
    gzip = false
    pattern = '^.+\.(png|jpg)$'
  [[deployment.matchers]]
    contentType = 'application/xml'
    gzip = true
    pattern = '^sitemap\.xml$'
  [[deployment.matchers]]
    gzip = true
    pattern = '^.+\.(html|xml|json)$'
  [[deployment.targets]]
    cloudFrontDistributionID = 'E1234567890ABCDEF0'
    exclude = '**.{heic,psd}'
    name = 'production'
    url = 's3://my_production_bucket?region=us-west-1'
  [[deployment.targets]]
    exclude = '**.{heic,psd}'
    name = 'staging'
    url = 's3://my_staging_bucket?region=us-west-1'

{
   "deployment": {
      "matchers": [
         {
            "cacheControl": "max-age=31536000, no-transform, public",
            "gzip": true,
            "pattern": "^.+\\.(js|css|svg|ttf)$"
         },
         {
            "cacheControl": "max-age=31536000, no-transform, public",
            "gzip": false,
            "pattern": "^.+\\.(png|jpg)$"
         },
         {
            "contentType": "application/xml",
            "gzip": true,
            "pattern": "^sitemap\\.xml$"
         },
         {
            "gzip": true,
            "pattern": "^.+\\.(html|xml|json)$"
         }
      ],
      "order": [
         ".jpg$",
         ".gif$"
      ],
      "targets": [
         {
            "cloudFrontDistributionID": "E1234567890ABCDEF0",
            "exclude": "**.{heic,psd}",
            "name": "production",
            "url": "s3://my_production_bucket?region=us-west-1"
         },
         {
            "exclude": "**.{heic,psd}",
            "name": "staging",
            "url": "s3://my_staging_bucket?region=us-west-1"
         }
      ]
   }
}

Last updated: March 12, 2025 : content: Miscellaneous edits (92ce95cbb)

Improve this page