github.com/goreleaser/goreleaser@v1.25.1/www/docs/customization/upload.md (about)

     1  # HTTP Upload
     2  
     3  GoReleaser supports building and pushing artifacts to HTTP servers using simple
     4  HTTP requests.
     5  
     6  ## How it works
     7  
     8  You can declare multiple `uploads` instances. All binaries generated by your
     9  `builds` section will be pushed to each configured upload.
    10  
    11  If you have only one `uploads` instance, the configuration is as easy as adding
    12  the upload target and a name to your `.goreleaser.yaml` file:
    13  
    14  ```yaml
    15  uploads:
    16    - name: production
    17      target: http://some.server/some/path/example-repo-local/{{ .ProjectName }}/{{ .Version }}/
    18  ```
    19  
    20  Prerequisites:
    21  
    22  - An HTTP server accepting HTTP requests
    23  - A user + password / client x509 certificate / API key with grants to upload an artifact
    24  
    25  !!! note
    26  
    27      authentication is optional and may be provided if the server requires it
    28      - user/pass is for Basic Authentication
    29      - client x509 certificate is for mutual TLS authentication (aka "mTLS")
    30  
    31  ### Target
    32  
    33  The `target` is the template of the URL to upload the artifacts to (_without_ the name of the artifact).
    34  
    35  An example configuration for `goreleaser` in upload mode `binary` with the target can look like:
    36  
    37  ```yaml
    38  - name: production
    39    mode: binary
    40    target: "http://some.server/some/path/example-repo-local/{{ .ProjectName }}/{{ .Version }}/{{ .Os }}/{{ .Arch }}{{ if .Arm }}{{ .Arm }}{{ end }}"
    41  ```
    42  
    43  and will result in an HTTP PUT request sent to
    44  `http://some.server/some/path/example-repo-local/goreleaser/1.0.0/Darwin/x86_64/goreleaser`.
    45  
    46  Supported variables:
    47  
    48  - `Version`
    49  - `Tag`
    50  - `ProjectName`
    51  - `ArtifactName`
    52  - `Os`
    53  - `Arch`
    54  - `Arm`
    55  
    56  !!! warning
    57  
    58      Variables `Os`, `Arch` and `Arm` are only supported in upload mode `binary`.
    59  
    60  For `archive` mode, it will also included the `LinuxPackage` type which is
    61  generated by `nfpm` and the like.
    62  
    63  ### Username
    64  
    65  Your configured username needs to be valid against your HTTP server.
    66  
    67  You can have the username set in the configuration file as shown above
    68  or you can have it read from an environment variable.
    69  The configured name of your HTTP server will be used to build the environment
    70  variable name.
    71  This way we support auth for multiple instances.
    72  This also means that the `name` per configured instance needs to be unique
    73  per GoReleaser configuration.
    74  
    75  The name of the environment variable will be `UPLOAD_NAME_USERNAME`.
    76  If your instance is named `production`, you can store the username in the
    77  environment variable `UPLOAD_PRODUCTION_USERNAME`.
    78  The name will be transformed to uppercase.
    79  
    80  If a configured username is found in the configuration file, then the
    81  environment variable is not used at all.
    82  
    83  This field is optional and is used only for basic http authentication.
    84  
    85  ### Password
    86  
    87  The password will be stored in an environment variable.
    88  The configured name of your HTTP server will be used.
    89  This way we support auth for multiple instances.
    90  This also means that the `name` per configured instance needs to be unique
    91  per GoReleaser configuration.
    92  
    93  The name of the environment variable will be `UPLOAD_NAME_SECRET`.
    94  If your instance is named `production`, you need to store the secret in the
    95  environment variable `UPLOAD_PRODUCTION_SECRET`.
    96  The name will be transformed to uppercase.
    97  
    98  This field is optional and is used only for basic http authentication.
    99  
   100  ### Client authorization with x509 certificate (mTLS / mutual TLS)
   101  
   102  If your artifactory server supports authorization with mTLS (client
   103  certificates), you can provide them by specifying the location of an x509
   104  certificate/key pair of pem-encode files.
   105  
   106  ```yaml
   107  uploads:
   108    - name: production
   109      client_x509_cert: path/to/client.cert.pem
   110      client_x509_key: path/to/client.key.pem
   111      target: "http://some.server/some/path/example-repo-local/{{ .ProjectName }}/{{ .Version }}/{{ .Os }}/{{ .Arch }}{{ if .Arm }}{{ .Arm }}{{ end }}"
   112  ```
   113  
   114  This will offer the client certificate during the TLS handshake, which your artifactory server may use to authenticate
   115  and authorize you to upload.
   116  
   117  ### Server authentication
   118  
   119  You can authenticate your TLS server adding a trusted X.509 certificate chain in
   120  your upload configuration.
   121  
   122  The trusted certificate chain will be used to validate the server certificates.
   123  
   124  You can set the trusted certificate chain using the `trusted_certificates`
   125  setting the upload section with PEM encoded certificates on a YAML literal block
   126  like this:
   127  
   128  ```yaml
   129  uploads:
   130    - name: "some HTTP/TLS server"
   131      #...(other settings)...
   132      trusted_certificates: |
   133        -----BEGIN CERTIFICATE-----
   134        MIIDrjCCApagAwIBAgIIShr2zchZo+8wDQYJKoZIhvcNAQENBQAwNTEXMBUGA1UE
   135        ...(edited content)...
   136        TyzMJasj5BPZrmKjJb6O/tOtEIJ66xPSBTxPShkEYHnB7A==
   137        -----END CERTIFICATE-----
   138        -----BEGIN CERTIFICATE-----
   139        MIIDrjCCApagAwIBAgIIShr2zchZo+8wDQYJKoZIhvcNAQENBQAwNTEXMBUGA1UE
   140        ...(edited content)...
   141        TyzMJasj5BPZrmKjJb6O/tOtEIJ66xPSBTxPShkEYHnB7A==
   142        -----END CERTIFICATE-----
   143  ```
   144  
   145  ## Customization
   146  
   147  Of course, you can customize a lot of things:
   148  
   149  ```yaml
   150  # .goreleaser.yaml
   151  uploads:
   152    # You can have multiple upload instances.
   153    - # Unique name of your upload instance. Used to identify the instance.
   154      name: production
   155  
   156      # HTTP method to use.
   157      #
   158      # Default: 'PUT'
   159      method: POST
   160  
   161      # IDs of the artifacts you want to upload.
   162      ids:
   163        - foo
   164        - bar
   165  
   166      # File extensions to filter for.
   167      # This might be useful if you have multiple packages with different
   168      # extensions with the same ID, and need to upload each extension to
   169      # a different place (e.g. nFPM packages).
   170      #
   171      # Since: v1.7
   172      exts:
   173        - deb
   174        - rpm
   175  
   176      # Matrix will run the upload for each possible combination of the given
   177      # values.
   178      # The keys will be available as template variables in the `target` and
   179      # `custom_headers` fields.
   180      #
   181      # This feature is only available in GoReleaser Pro.
   182      # Since: v1.20 (pro)
   183      matrix:
   184        foo: [bar zaz]
   185        something: [foobar somethingelse anotherthing]
   186  
   187      # Upload mode. Valid options are `binary` and `archive`.
   188      # If mode is `archive`, variables _Os_, _Arch_ and _Arm_ for target name are not supported.
   189      # In that case these variables are empty.
   190      #
   191      # Default: 'archive'
   192      mode: archive
   193  
   194      # URL to be used as target of the HTTP request
   195      #
   196      # Templates: allowed
   197      target: https://some.server/some/path/example-repo-local/{{ .ProjectName }}/{{ .Version }}/
   198  
   199      # Custom artifact name.
   200      # If enable, you must supply the name of the Artifact as part of the Target
   201      # URL as it will not be automatically append to the end of the URL, its
   202      # pre-computed name is available as _ArtifactName_ for example
   203      # target: https://some.server/some/path/example-repo-local/{{ .ArtifactName }};deb.distribution=xenial
   204      custom_artifact_name: true
   205  
   206      # An optional username that will be used for the deployment for basic authn
   207      username: deployuser
   208  
   209      # Client certificate and key (when provided, added as client cert to TLS connections)
   210      #
   211      # Since: v1.11
   212      client_x509_cert: /path/to/client.cert.pem
   213      client_x509_key: /path/to/client.key.pem
   214  
   215      # An optional header you can use to tell GoReleaser to pass the artifact's
   216      # SHA256 checksum within the upload request.
   217      checksum_header: -X-SHA256-Sum
   218  
   219      # A map of custom headers e.g. to support required content types or auth schemes.
   220      custom_headers:
   221        JOB-TOKEN: "{{ .Env.CI_JOB_TOKEN }}"
   222  
   223      # Upload checksums.
   224      checksum: true
   225  
   226      # Upload metadata.json and artifacts.json.
   227      #
   228      # Since: v1.25
   229      meta: true
   230  
   231      # Upload signatures.
   232      signature: true
   233  
   234      # Certificate chain used to validate server certificates
   235      trusted_certificates: |
   236        -----BEGIN CERTIFICATE-----
   237        MIIDrjCCApagAwIBAgIIShr2zchZo+8wDQYJKoZIhvcNAQENBQAwNTEXMBUGA1UE
   238        ...(edited content)...
   239        TyzMJasj5BPZrmKjJb6O/tOtEIJ66xPSBTxPShkEYHnB7A==
   240        -----END CERTIFICATE-----
   241  ```
   242  
   243  !!! success "GoReleaser Pro"
   244  
   245      Some options are only available in [GoReleaser Pro feature](/pro/).
   246  
   247  These settings should allow you to push your artifacts into multiple HTTP
   248  servers.
   249  
   250  !!! tip
   251  
   252      Learn more about the [name template engine](/customization/templates/).