diff --git a/README.md b/README.md index 769f5f4..ba00b6a 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,10 @@ With `tag` omitted, `check` will instead detect tags based on semver versions `check` will only detect semver tags that include the variant suffix (e.g. `1.2.3-stretch`). +_This resource comes with Concourse by default. You can override the version +you use within your pipeline if the built-in one is not working for you for +some reason_ + ## Comparison to `docker-image` resource This resource is intended as a replacement for the [Docker Image @@ -40,82 +44,194 @@ differences: ## Source Configuration -* `repository`: *Required.* The name of the repository, e.g. `alpine` or - `concourse/concourse`. - - *Note: If using ecr you only need the repository name, not the full URI e.g. - `alpine` not `012345678910.dkr.ecr.us-east-1.amazonaws.com/alpine`* - -* `insecure`: *Optional. Default `false`* Allow insecure registry. - -* `tag`: *Optional.* Instead of monitoring semver tags, monitor a single tag - for changes (based on digest). - -* `variant`: *Optional.* Detect only tags matching this variant suffix, and - push version tags with this suffix applied. For example, a value of `stretch` - would be used for tags like `1.2.3-stretch`. This is typically used *without* - `tag` - if it is set, this value will only used for pushing, not checking. - -* `semver_constraint`: *Optional.* Constrain the returned semver tags according - to a semver constraint, e.g. `"~1.2.x"`, `">= 1.2 < 3.0.0 || >= 4.2.3"`. - Follows the rules outlined in https://github.com/Masterminds/semver#checking-version-constraints. - -* `username` and `password`: *Optional.* A username and password to use when - authenticating to the registry. Must be specified for private repos or when - using `put`. - -* `aws_access_key_id`: *Optional. Default `""`.* The access key ID to use for - authenticating with ECR. - -* `aws_secret_access_key`: *Optional. Default `""`.* The secret access key to - use for authenticating with ECR. - -* `aws_session_token`: *Optional. Default `""`.* The session token to use - for authenticating with STS credentials with ECR. - -* `aws_region`: *Optional. Default `""`.* The region to use for accessing ECR. This is required if you are using ECR. This region will help determine the full repository URL you are accessing (e.g., `012345678910.dkr.ecr.us-east-1.amazonaws.com`) - -* `aws_role_arn`: *Optional. Default `""`.* If set, then this role will be - assumed before authenticating to ECR. An error will occur if `aws_role_arns` - is also specified. This is kept for backward compatibility. - -* `aws_role_arns`: *Optional. Default `""`.* An array of AWS IAM roles. - If set, these roles will be assumed in the specified order before authenticating to ECR. - An error will occur if `aws_role_arn` is also specified. - -* `debug`: *Optional. Default `false`.* If set, progress bars will be disabled - and debugging output will be printed instead. - -* `registry_mirror`: *Optional.* - * `host`: *Required.* A hostname pointing to a Docker registry mirror service. Note that this is only used if no registry hostname prefix is specified in the `repository`. If the `repository` contains a registry hostname prefix -- such as `my-registry.com/foo/bar` -- the `registry_mirror` is ignored and the explicitly declared registry in the `repository` value is used. - * `username` and `password`: *Optional.* A username and password to use when - authenticating to the mirror. - -* `content_trust`: *Optional.* Configuration about content trust. - * `server`: *Optional.* URL for the notary server. (equal to `DOCKER_CONTENT_TRUST_SERVER`) - * `repository_key_id`: *Required.* Target key's ID used to sign the trusted collection, could be retrieved by `notary key list` - * `repository_key`: *Required.* Target key used to sign the trusted collection. - * `repository_passphrase`: *Required.* The passphrase of the signing/target key. (equal to `DOCKER_CONTENT_TRUST_REPOSITORY_PASSPHRASE`) - * `tls_key`: *Optional. Default `""`* TLS key for the notary server. - * `tls_cert`: *Optional. Default `""`* TLS certificate for the notary server. - -* `ca_certs`: *Optional.* An array of PEM-encoded CA certificates: - - ```yaml - ca_certs: - - | - -----BEGIN CERTIFICATE----- - ... - -----END CERTIFICATE----- - - | - -----BEGIN CERTIFICATE----- - ... - -----END CERTIFICATE----- - ``` - - Each entry specifies the x509 CA certificate for the trusted docker registry. - This is used to validate the certificate of the docker registry when the - registry's certificate is signed by a custom authority (or itself). +
Field Name | +Description | +
---|---|
repository (Required) |
+
+ The URI of the image repository, e.g. alpine or
+ ghcr.io/package/image . Defaults to checking
+ docker.io if no hostname is provided in the URI.
+ + Note: If using ecr you only need the repository name, + not the full URI e.g. alpine not
+ 012345678910.dkr.ecr.us-east-1.amazonaws.com/alpine
+ |
+
insecure (Optional)Default: false |
+ + Allow insecure registry. + | +
tag (Optional)Default: latest |
+ + Instead of monitoring semver tags, monitor a single tag for changes (based + on digest). + | +
variant (Optional) |
+
+ Detect only tags matching this variant suffix, and push version tags with
+ this suffix applied. For example, a value of stretch would be
+ used for tags like 1.2.3-stretch . This is typically used
+ without tag - if it is set, this value will only used
+ for pushing, not checking.
+ |
+
semver_constraint (Optional) |
+
+ Constrain the returned semver tags according to a semver constraint, e.g.
+ "~1.2.x" , ">= 1.2 < 3.0.0 || >= 4.2.3" .
+ + Follows the rules outlined in + https://github.com/Masterminds/semver#checking-version-constraints + |
+
username and password (Optional) |
+
+ A username and password to use when authenticating to the registry. Must be
+ specified for private repos or when using put .
+ |
+
aws_access_key_id (Optional) |
+ + The access key ID to use for authenticating with ECR. + | +
aws_secret_access_key (Optional) |
+ + The secret access key to use for authenticating with ECR. + | +
aws_session_token (Optional) |
+ + The session token to use for authenticating with STS credentials with ECR. + | +
aws_region (Optional) |
+
+ The region to use for accessing ECR. This is required if you are using ECR.
+ This region will help determine the full repository URL you are accessing
+ (e.g., 012345678910.dkr.ecr.us-east-1.amazonaws.com )
+ |
+
aws_role_arn (Optional) |
+
+ If set, then this role will be assumed before authenticating to ECR. An
+ error will occur if aws_role_arns is also specified. This is
+ kept for backward compatibility.
+ |
+
aws_role_arns (Optional) |
+
+ An array of AWS IAM roles. If set, these roles will be assumed in the
+ specified order before authenticating to ECR. An error will occur if
+ aws_role_arn is also specified.
+ |
+
debug (Optional)Default: false |
+ + If set, progress bars will be disabled and debugging output will be printed + instead. + | +
registry_mirror (Optional) |
+
+
|
+
content_trust (Optional) |
+
+
|
+
ca_certs (Optional) |
+
+ An array of PEM-encoded CA certificates.
+ Example:
+
+ca_certs:
+- |
+ -----BEGIN CERTIFICATE-----
+ ...
+ -----END CERTIFICATE-----
+- |
+ -----BEGIN CERTIFICATE-----
+ ...
+ -----END CERTIFICATE-----
+
+
+ Each entry specifies the x509 CA certificate for the trusted docker
+ registry. This is used to validate the certificate of the docker registry
+ when the registry's certificate is signed by a custom authority (or
+ itself).
+ |
+
Parameter | +Description | +
---|---|
format (Optional)Default: rootfs |
+ The format to fetch the image as. Accepted values are: rootfs , oci |
+
skip_download (Optional)Default: false |
+
+ Skip downloading the image. Useful if you want to trigger a job without
+ using the object or when running after a put step and not
+ needing to download the image you just uploaded.
+ |
+
Parameter | +Description | +
---|---|
image (Required) |
+
+ The path to the oci image tarball to upload. Expanded with
+ filepath.Glob
+ |
+
version (Optional) |
+ + A version number to use as a tag. + | +
bump_aliases (Optional)Default: false |
+
+ When set to true and version is specified,
+ automatically bump alias tags for the version.
+ For example, when pushing version 1.2.3 , push the same image
+ to the following tags:
+
variant is configured as foo , push the same
+ image to the following tags:
+
|
+
additional_tags (Optional) |
+
+ The path to a file with whitespace-separated list of tag values to tag the
+ image with (in addition to the tag configured in source ).
+ |
+