Configure deployment

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 RE2 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) An RE2 regular expression used to match paths. Paths are converted to use forward slashes (/) before matching.

Destination URLs

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:

• Ceph
• MinIO
• SeaweedFS

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"
         }
      ]
   }
}