{"id":13441110,"url":"https://github.com/concourse/registry-image-resource","last_synced_at":"2026-01-06T20:34:00.930Z","repository":{"id":34058089,"uuid":"143379187","full_name":"concourse/registry-image-resource","owner":"concourse","description":"a resource for images in a Docker registry","archived":false,"fork":false,"pushed_at":"2025-05-13T17:13:40.000Z","size":844,"stargazers_count":91,"open_issues_count":39,"forks_count":109,"subscribers_count":21,"default_branch":"master","last_synced_at":"2025-05-13T18:29:15.312Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/concourse.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["taylorsilva"]}},"created_at":"2018-08-03T04:50:42.000Z","updated_at":"2025-05-13T17:13:49.000Z","dependencies_parsed_at":"2024-02-26T19:47:38.405Z","dependency_job_id":"9c08c08c-5e23-470a-8f88-229a486aa996","html_url":"https://github.com/concourse/registry-image-resource","commit_stats":{"total_commits":267,"total_committers":46,"mean_commits":5.804347826086956,"dds":0.6853932584269663,"last_synced_commit":"273553a9af5255f4218facf46f32856756406e2b"},"previous_names":[],"tags_count":46,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/concourse%2Fregistry-image-resource","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/concourse%2Fregistry-image-resource/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/concourse%2Fregistry-image-resource/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/concourse%2Fregistry-image-resource/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/concourse","download_url":"https://codeload.github.com/concourse/registry-image-resource/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254169056,"owners_count":22026207,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T03:01:30.042Z","updated_at":"2026-01-06T20:34:00.896Z","avatar_url":"https://github.com/concourse.png","language":"Go","funding_links":["https://github.com/sponsors/taylorsilva"],"categories":["HarmonyOS"],"sub_categories":["Windows Manager"],"readme":"# Registry Image Resource\n\nSupports checking, fetching, and pushing of images to Docker registries.\n\n\u003ca href=\"https://ci.concourse-ci.org/teams/main/pipelines/resource/jobs/build?vars.type=%22registry-image%22\"\u003e\n  \u003cimg src=\"https://ci.concourse-ci.org/api/v1/teams/main/pipelines/resource/jobs/build/badge?vars.type=%22registry-image%22\" alt=\"Build Status\"\u003e\n\u003c/a\u003e\n\n\nThis resource can be used in three ways: [with `tag`\nspecified](#check-step-check-script-with-tag-discover-new-digests-for-the-tag), [with `tag_regex` specified](#check-step-check-script-with-tag_regex-discover-tags-matching-regex), or [with neither\n`tag` nor `tag_regex` specified](#check-step-check-script-without-tag-or-tag_regex-discover-semver-tags).\n\nWith `tag` specified, `check` will detect changes to the digest the tag points\nto, and `out` will always push to the specified tag. This is to be used in\nsimpler cases where no real versioning exists.\n\nWith `tag_regex` specified, `check` will instead detect tags based on the regex\nprovided. If `created_at_sort` is set to `true`, the tags will be sorted in descending order by the creation time.\nThis is useful when you want to get the latest tag based on the regex (see Docker registry issue\n[here](https://github.com/docker/hub-feedback/issues/185)).\n\nWith `tag` and `tag_regex` both omitted, `check` will instead detect tags based on semver versions\n(e.g. `1.2.3`) and return them in semver order. With `variant` included,\n`check` will only detect semver tags that include the variant suffix (e.g.\n`1.2.3-stretch`).\n\n_This resource comes with Concourse by default. You can override the version\nyou use within your pipeline if the built-in one is not working for you for\nsome reason_\n\n## Comparison to `docker-image` resource\n\nThis resource is intended as a replacement for the [Docker Image\nresource](https://github.com/concourse/docker-image-resource). Here are the key\ndifferences:\n\n* This resource is implemented in pure Go and does not use the Docker daemon or\n  CLI. This makes it safer (no need for `privileged: true`), more efficient,\n  and less error-prone (now that we're using Go APIs and not parsing `docker`\n  CLI output).\n\n* This resource has stronger test coverage.\n\n* This resource does not and will never support building - only registry image\n  pushing/pulling. Building should instead be done with something like the\n  [`oci-build` task](https://github.com/vito/oci-build-task) (or anything\n  that can produce OCI image tarballs).\n\n* A goal of this resource is to stay as focused and simple as possible. The\n  Docker Image resource grew way too large and complicated. There are simply\n  too many ways to build and publish Docker images. It will be easier to\n  support many smaller resources + tasks rather than one huge interface.\n\n\n## Source Configuration\n\n\u003ctable\u003e\n\u003cthead\u003e\n  \u003ctr\u003e\n    \u003cth\u003eField Name\u003c/th\u003e\n    \u003cth\u003eDescription\u003c/th\u003e\n  \u003c/tr\u003e\n\u003c/thead\u003e\n\u003ctbody\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ccode\u003erepository\u003c/code\u003e \u003cem\u003e(Required)\u003c/em\u003e\u003c/td\u003e\n    \u003ctd\u003e\n    The URI of the image repository, e.g. \u003ccode\u003ealpine\u003c/code\u003e or\n    \u003ccode\u003eghcr.io/package/image\u003c/code\u003e. Defaults to checking\n    \u003ccode\u003edocker.io\u003c/code\u003e if no hostname is provided in the URI.\n    \u003cbr\u003e\n    \u003cem\u003e\u003cstrong\u003eNote:\u003c/strong\u003e If using ecr you only need the repository name,\n    not the full URI e.g. \u003ccode\u003ealpine\u003c/code\u003e not\n    \u003ccode\u003e012345678910.dkr.ecr.us-east-1.amazonaws.com/alpine\u003c/code\u003e. ECR usage\n    is NOT automatically detected. You must set the \u003ccode\u003eaws_region\u003c/code\u003e to\n    tell the resource to automatically use ECR.\u003c/em\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ccode\u003einsecure\u003c/code\u003e \u003cem\u003e(Optional)\u003cbr\u003eDefault: false\u003c/em\u003e\u003c/td\u003e\n    \u003ctd\u003e\n    Allow insecure registry.\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ccode\u003etag\u003c/code\u003e \u003cem\u003e(Optional)\u003cbr\u003eDefault: \u003ccode\u003elatest\u003c/code\u003e\u003c/em\u003e\u003c/td\u003e\n    \u003ctd\u003e\n    Instead of monitoring semver tags, monitor a single tag for changes (based\n    on digest).\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ccode\u003etag_regex\u003c/code\u003e \u003cem\u003e(Optional)\u003c/em\u003e\u003c/td\u003e\n    \u003ctd\u003e\n    Instead of monitoring semver tags, monitor for tags based on a regex provided.\n    \u003cbr\u003eThe syntax of the regular expressions accepted is the same\n    general syntax used by Perl, Python, and other languages. More precisely,\n    it is the syntax accepted by RE2 and described at https://golang.org/s/re2syntax\n    \u003cbr\u003eNote if used, this will override all Semver constraints and features.\n    By default, order of tags is not guaranteed. If you want to sort the tags in descending order, set `created_at_sort` to `true`.\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n  \u003ctd\u003e\u003ccode\u003ecreated_at_sort\u003c/code\u003e \u003cem\u003e(Optional)\u003cbr\u003eDefault: false\u003c/em\u003e\u003c/td\u003e\n  \u003ctd\u003e\n    If set to `true`, the tags will be sorted in descending order using the creation time from the image history.\n    This is useful when you want to get the latest tag based on the tag_regex.\n  \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ccode\u003evariant\u003c/code\u003e \u003cem\u003e(Optional)\u003c/em\u003e\u003c/td\u003e\n    \u003ctd\u003e\n    Detect only tags matching this variant suffix, and push version tags with\n    this suffix applied. For example, a value of \u003ccode\u003estretch\u003c/code\u003e would be\n    used for tags like \u003ccode\u003e1.2.3-stretch\u003c/code\u003e. This is typically used\n    \u003cem\u003ewithout\u003c/em\u003e \u003ccode\u003etag\u003c/code\u003e - if it is set, this value will only used\n    for pushing, not checking.\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ccode\u003esemver_constraint\u003c/code\u003e \u003cem\u003e(Optional)\u003c/em\u003e\u003c/td\u003e\n    \u003ctd\u003e\n    Constrain the returned semver tags according to a semver constraint, e.g.\n    \u003ccode\u003e\"~1.2.x\"\u003c/code\u003e, \u003ccode\u003e\"\u003e= 1.2 \u003c 3.0.0 || \u003e= 4.2.3\"\u003c/code\u003e.\n    \u003cbr\u003e\n    Follows the rules outlined in\n    https://github.com/Masterminds/semver#checking-version-constraints\n    \u003cbr\u003e\n    If the value appends with \u003ccode\u003e-0\u003c/code\u003e for pre-release versions,\n    \u003ccode\u003epre_releases\u003c/code\u003e needs to be \u003ccode\u003etrue\u003c/code\u003e.\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ccode\u003epre_releases\u003c/code\u003e \u003cem\u003e(Optional)\u003c/em\u003e\u003c/td\u003e\n    \u003ctd\u003e\n    By default, pre-release versions are ignored. With `pre_releases: true`, they\n    will be included.\n    \u003cbr\u003e\n    Note however that variants and pre-releases both use the same syntax:\n    `1.2.3-alpine` is technically also valid syntax for a Semver prerelease. For\n    this reason, the resource will only consider prerelease data starting with\n    `alpha`, `beta`, or `rc` as a proper prerelease, or values provided by\n    `pre_release_prefixes`, treating anything else as a variant.\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ccode\u003epre_release_prefixes\u003c/code\u003e \u003cem\u003e(Optional)\u003c/em\u003e\u003c/td\u003e\n    \u003ctd\u003e\n    An array of strings, where each string is an additional pre-release prefix that should be found (e.g. `build.3`). `pre_releases` must be set to `true`.\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ccode\u003eusername\u003c/code\u003e and \u003ccode\u003epassword\u003c/code\u003e \u003cem\u003e(Optional)\u003c/em\u003e\u003c/td\u003e\n    \u003ctd\u003e\n    A username and password to use when authenticating to the registry. Must be\n    specified for private repos or when using \u003ccode\u003eput\u003c/code\u003e.\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ccode\u003eaws_access_key_id\u003c/code\u003e \u003cem\u003e(Optional)\u003c/em\u003e\u003c/td\u003e\n    \u003ctd\u003e\n    The access key ID to use for authenticating with ECR.\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ccode\u003eaws_secret_access_key\u003c/code\u003e \u003cem\u003e(Optional)\u003c/em\u003e\u003c/td\u003e\n    \u003ctd\u003e\n    The secret access key to use for authenticating with ECR.\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ccode\u003eaws_session_token\u003c/code\u003e \u003cem\u003e(Optional)\u003c/em\u003e\u003c/td\u003e\n    \u003ctd\u003e\n    The session token to use for authenticating with STS credentials with ECR.\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ccode\u003eaws_region\u003c/code\u003e \u003cem\u003e(Optional)\u003c/em\u003e\u003c/td\u003e\n    \u003ctd\u003e\n    The region to use for accessing ECR. This is required if you are using ECR.\n    This region will help determine the full repository URL you are accessing\n    (e.g., \u003ccode\u003e012345678910.dkr.ecr.us-east-1.amazonaws.com\u003c/code\u003e)\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ccode\u003eaws_role_arn\u003c/code\u003e \u003cem\u003e(Optional)\u003c/em\u003e\u003c/td\u003e\n    \u003ctd\u003e\n    If set, then this role will be assumed before authenticating to ECR. An\n    error will occur if \u003ccode\u003eaws_role_arns\u003c/code\u003e is also specified. This is\n    kept for backward compatibility.\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ccode\u003eaws_role_arns\u003c/code\u003e \u003cem\u003e(Optional)\u003c/em\u003e\u003c/td\u003e\n    \u003ctd\u003e\n    An array of AWS IAM roles. If set, these roles will be assumed in the\n    specified order before authenticating to ECR. An error will occur if\n    \u003ccode\u003eaws_role_arn\u003c/code\u003e is also specified.\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ccode\u003eaws_account_id\u003c/code\u003e \u003cem\u003e(Optional)\u003c/em\u003e\u003c/td\u003e\n    \u003ctd\u003e\n    The AWS Account ID that the image is located in. Useful if interacting with\n    images in another account. If omitted then the current AWS account ID will\n    be used. Be sure to wrap the account ID in quotes so it is parsed as a\n    string instead of a number.\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ccode\u003eplatform\u003c/code\u003e \u003cem\u003e(Optional)\u003c/em\u003e\u003c/td\u003e\n    \u003ctd\u003e\n      \u003cul\u003e\n        \u003cli\u003e\n          \u003ccode\u003earchitecture\u003c/code\u003e \u003cem\u003e(Optional)\u003c/em\u003e:\n          Architecture the image is built for (e.g. `amd64`, `arm64/v8`). If not\n          specified, will default to https://pkg.go.dev/runtime#GOARCH.\n        \u003c/li\u003e\n        \u003cli\u003e\n          \u003ccode\u003eos\u003c/code\u003e \u003cem\u003e(Optional)\u003c/em\u003e:\n          OS the image is built for (e.g. `linux`, `darwin`, `windows`). If not\n          specified, will default to https://pkg.go.dev/runtime#GOOS.\n        \u003c/li\u003e\n      \u003c/ul\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ccode\u003edebug\u003c/code\u003e \u003cem\u003e(Optional)\u003cbr\u003eDefault: false\u003c/em\u003e\u003c/td\u003e\n    \u003ctd\u003e\n    If set, progress bars will be disabled and debugging output will be printed\n    instead.\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ccode\u003eregistry_mirror\u003c/code\u003e \u003cem\u003e(Optional)\u003c/em\u003e\u003c/td\u003e\n    \u003ctd\u003e\n      \u003cul\u003e\n        \u003cli\u003e\n          \u003ccode\u003ehost\u003c/code\u003e \u003cem\u003e(Required)\u003c/em\u003e:\n          A hostname pointing to a Docker registry mirror service. Note that this\n          is only used if no registry hostname prefix is specified in the\n          \u003ccode\u003erepository\u003c/code\u003e key. If the \u003ccode\u003erepository\u003c/code\u003e contains a\n          registry hostname, such as \u003ccode\u003emy-registry.com/foo/bar\u003c/code\u003e, the\n          \u003ccode\u003eregistry_mirror\u003c/code\u003e is ignored and the explicitly declared\n          registry in the \u003ccode\u003erepository\u003c/code\u003e key is used.\n        \u003c/li\u003e\n        \u003cli\u003e\n          \u003ccode\u003eusername\u003c/code\u003e and \u003ccode\u003epassword\u003c/code\u003e \u003cem\u003e(Optional)\u003c/em\u003e:\n          A username and password to use when authenticating to the mirror.\n        \u003c/li\u003e\n      \u003c/ul\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ccode\u003econtent_trust\u003c/code\u003e \u003cem\u003e(Optional)\u003c/em\u003e\u003c/td\u003e\n    \u003ctd\u003e\n      \u003cul\u003e\n        \u003cli\u003e\n          \u003ccode\u003eserver\u003c/code\u003e \u003cem\u003e(Optional)\u003c/em\u003e:\n          URL for the notary server. (equal to\n          \u003ccode\u003eDOCKER_CONTENT_TRUST_SERVER\u003c/code\u003e)\n        \u003c/li\u003e\n        \u003cli\u003e\n          \u003ccode\u003erepository_key_id\u003c/code\u003e \u003cem\u003e(Required)\u003c/em\u003e:\n          Target key's ID used to sign the trusted collection, could be retrieved\n          by \u003ccode\u003enotary key list\u003c/code\u003e\n        \u003c/li\u003e\n        \u003cli\u003e\n          \u003ccode\u003erepository_key\u003c/code\u003e \u003cem\u003e(Required)\u003c/em\u003e:\n          Target key used to sign the trusted collection.\n        \u003c/li\u003e\n        \u003cli\u003e\n          \u003ccode\u003erepository_passphrase\u003c/code\u003e \u003cem\u003e(Required)\u003c/em\u003e:\n          The passphrase of the signing/target key. (equal to\n          \u003ccode\u003eDOCKER_CONTENT_TRUST_REPOSITORY_PASSPHRASE\u003c/code\u003e)\n        \u003c/li\u003e\n        \u003cli\u003e\n          \u003ccode\u003etls_key\u003c/code\u003e \u003cem\u003e(Optional)\u003c/em\u003e:\n          TLS key for the notary server.\n        \u003c/li\u003e\n        \u003cli\u003e\n          \u003ccode\u003etls_cert\u003c/code\u003e \u003cem\u003e(Optional)\u003c/em\u003e:\n          TLS certificate for the notary server.\n        \u003c/li\u003e\n        \u003cli\u003e\n          \u003ccode\u003eusername\u003c/code\u003e \u003cem\u003e(Optional)\u003c/em\u003e:\n          Username for authorize Docker Registry with a Notary server(`content_trust.server`) attached.\n        \u003c/li\u003e\n        \u003cli\u003e\n          \u003ccode\u003epassword\u003c/code\u003e \u003cem\u003e(Optional)\u003c/em\u003e:\n          Password for authorize Docker Registry with a Notary server(`content_trust.server`) attached.\n        \u003c/li\u003e\n        \u003cli\u003e\n          \u003ccode\u003escopes\u003c/code\u003e \u003cem\u003e(Optional)\u003c/em\u003e:\n          What access for the resources requested, should be one of ['pull', 'push,pull', 'catalog']\n        \u003c/li\u003e\n      \u003c/ul\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ccode\u003eca_certs\u003c/code\u003e\u003cem\u003e(Optional)\u003c/em\u003e\u003c/td\u003e\n    \u003ctd\u003e\n    An array of PEM-encoded CA certificates.\n    Example:\n    \u003cpre lang=\"yaml\"\u003e\nca_certs:\n- |\n  -----BEGIN CERTIFICATE-----\n  ...\n  -----END CERTIFICATE-----\n- |\n  -----BEGIN CERTIFICATE-----\n  ...\n  -----END CERTIFICATE-----\n    \u003c/pre\u003e\n\n  Each entry specifies the x509 CA certificate for the trusted docker\n  registry. This is used to validate the certificate of the docker registry\n  when the registry's certificate is signed by a custom authority (or\n  itself).\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/tbody\u003e\n\u003c/table\u003e\n\n### Signing with Docker Hub\n\nConfigure Docker Content Trust for use with the [Docker Hub](https:/hub.docker.io) and Notary service by specifying the above source parameters as follows:\n\n* `repository_key` should be set to the contents of the DCT key file located in your ~/.docker/trust/private directory.\n* `repository_key_id` should be set to the full key itself, which is also the filename of the key file mentioned above, without the .key extension.\n\nConsider the following resource:\n\n```yaml\nresources:\n- name: trusted-image\n  type: registry-image\n  source:\n    repository: docker.io/foo/bar\n    username: ((registry_user))\n    password: ((registry_pass))\n    content_trust:\n      repository_key_id: ((registry_key_id))\n      repository_key: ((registry_key))\n      repository_passphrase: ((registry_passphrase))\n```\n\nSpecify the values for these variables as shown in the following static variable file, or preferrably in a configured [credential manager](https://concourse-ci.org/creds.html):\n\n```yaml\nregistry_user: jertel\nregistry_pass: my_docker_hub_token\nregistry_passphrase: my_dct_key_passphrase\nregistry_key_id: 1452a842871e529ffc2be29a012618e1b2a0e6984a89e92e34b5a0fc21a04cd\nregistry_key: |\n  -----BEGIN ENCRYPTED PRIVATE KEY-----\n  role: jertel\n\n  MIhsj2sd41fwaa...\n  -----END ENCRYPTED PRIVATE KEY-----\n```\n\n**NOTE** This configuration only applies to the `out` action. `check` \u0026 `in` aren't impacted. Hence, it would be possible to `check` or use `in` to get unsigned images.\n\n## Behavior\n\n### `check` Step (`check` script) with `tag`: discover new digests for the tag\n\nReports the current digest that the registry has for the tag configured in\n`source`.\n\n### `check` Step (`check` script) with `tag_regex`: discover tags matching regex\n\nReports the current digest that the registry has for tags matching the regex\nconfigured in `source`. They will be returned in the same order that the source repository lists them unless `created_at_sort`\nis set to `true`.\n\n### `check` Step (`check` script) without `tag` or `tag_regex`: discover semver tags\n\nDetects tags which contain semver version numbers. Version numbers do not\nneed to contain all 3 segments (major/minor/patch).\n\nEach unique digest will be returned only once, with the most specific version\ntag available. This is to handle \"alias\" tags like `1`, `1.2` pointing to\n`1.2.3`.\n\nNote: the initial `check` call will return *all valid versions*, which is\nunlike most resources which only return the latest version. This is an\nintentional choice which will become the normal behavior for resources in\nthe future (per concourse/rfcs#38).\n\nExample:\n\n```yaml\nresources:\n- name: concourse\n  type: registry-image\n  source: {repository: concourse/concourse}\n```\n\nThe above resource definition would detect the following versions:\n\n```json\n[\n  {\n    \"tag\": \"1.6.0\",\n    \"digest\": \"sha256:e1ad01d3227569ad869bdb6bd68cf1ea54057566c25bae38b99d92bbe9f28d78\"\n  },\n  {\n    \"tag\": \"2.0.0\",\n    \"digest\": \"sha256:9ab8d1021d97c6602abbb2c40548eab67aa7babca22f6fe33ab80f4cbf8ea92c\"\n  },\n  // ...\n]\n```\n\n#### Variant tags\n\nDocker repositories have a pretty common convention of adding `-SUFFIX` to\ntags to denote \"variant\" images, i.e. the same version but with a different\nbase image or dependency. For example, `1.2.3` vs `1.2.3-alpine`.\n\nWith a `variant` value specified, only semver tags with the matching variant\nwill be detected. With `variant` omitted, tags which include a variant are\nignored.\n\nNote: some image tags actually include *mutliple* variants, e.g.\n`1.2.3-php7.3-apache`. With a variant of only `apache` configured, these tags\nwill be skipped to avoid accidentally using multiple variants. In order to\nuse these tags, you must specify the full variant combination, e.g.\n`php7.3-apache`.\n\nExample:\n\n```yaml\nresources:\n- name: concourse\n  type: registry-image\n  source:\n    repository: concourse/concourse\n    variant: ubuntu\n```\n\nThe above resource definition would detect the following versions:\n\n```json\n[\n  {\n    \"tag\": \"5.2.1-ubuntu\",\n    \"digest\": \"sha256:91f5d180d84ee4b2cedfae45771adac62c67c3f5f615448d3c34057c09404f27\"\n  },\n  {\n    \"tag\": \"5.2.2-ubuntu\",\n    \"digest\": \"sha256:cb631d788797f0fbbe72a00afd18e5e4bced356e1b988d1862dc9565130a6226\"\n  },\n  // ...\n]\n```\n\n\n\n### `get` Step (`in` script): fetch an image\n\nFetches an image at the exact digest specified by the version.\n\n#### `get` Step `params`\n\n\u003ctable\u003e\n\u003cthead\u003e\n  \u003ctr\u003e\n    \u003cth\u003eParameter\u003c/th\u003e\n    \u003cth\u003eDescription\u003c/th\u003e\n  \u003c/tr\u003e\n\u003c/thead\u003e\n\u003ctbody\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ccode\u003eformat\u003c/code\u003e \u003cem\u003e(Optional)\u003cbr\u003eDefault: \u003ccode\u003erootfs\u003c/code\u003e\u003c/em\u003e\u003c/td\u003e\n    \u003ctd\u003eThe format to fetch the image as. Accepted values are: \u003ccode\u003erootfs\u003c/code\u003e, \u003ccode\u003eoci\u003c/code\u003e, \u003ccode\u003eoci-layout\u003c/code\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ccode\u003eplatform\u003c/code\u003e \u003cem\u003e(Optional)\u003c/em\u003e\u003c/td\u003e\n    \u003ctd\u003e\n        \u003cul\u003e\n            \u003cli\u003e\n            \u003ccode\u003earchitecture\u003c/code\u003e \u003cem\u003e(Optional)\u003c/em\u003e:\n            Architecture the image is built for (e.g. `amd64`, `arm64/v8`). If not\n            specified, will default to https://pkg.go.dev/runtime#GOARCH.\n            \u003c/li\u003e\n            \u003cli\u003e\n            \u003ccode\u003eos\u003c/code\u003e \u003cem\u003e(Optional)\u003c/em\u003e:\n            OS the image is built for (e.g. `linux`, `darwin`, `windows`). If not\n            specified, will default to https://pkg.go.dev/runtime#GOOS.\n            \u003c/li\u003e\n        \u003c/ul\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ccode\u003eskip_download\u003c/code\u003e \u003cem\u003e(Optional)\u003cbr\u003eDefault: false\u003c/em\u003e\u003c/td\u003e\n    \u003ctd\u003e\n      Skip downloading the image. Useful if you want to trigger a job without\n      using the object or when running after a \u003ccode\u003eput\u003c/code\u003e step and not\n      needing to download the image you just uploaded.\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/tbody\u003e\n\u003c/table\u003e\n\n#### Files created by the `get` step\n\nThe resource will produce the following files:\n\n* `./repository`: A file containing the image's full repository name, e.g. `concourse/concourse`.\n  For ECR images, this will include the registry the image was pulled from.\n* `./tag`: A file containing the tag from the version.\n* `./digest`: A file containing the digest from the version, e.g. `sha256:...`.\n\nThe remaining files depend on the configuration value for `format`:\n\n##### `rootfs` Format\n\nThe `rootfs` format will fetch and unpack the image for use by Concourse task\nand resource type images.\n\nThis the default for the sake of brevity in pipelines and task configs.\n\nIn this format, the resource will produce the following files:\n\n* `./rootfs/...`: the unpacked rootfs produced by the image.\n* `./metadata.json`: the runtime information to propagate to Concourse.\n* `./labels.json`: A file containing a JSON map of image labels, e.g. `{ \"commit\": \"4e5c4ea\" }`\n\n##### `oci` Format\n\nThe `oci` format will fetch the image and write it to disk in a format similar\nto running `docker save`.\n\nIn this format, the resource will produce the following files:\n\n* `./image.tar`: the OCI image tarball, suitable for passing to `docker load`.\n* `./labels.json`: A file containing a JSON map of image labels, e.g. `{ \"commit\": \"4e5c4ea\" }`\n\n##### `oci-layout` Format\n\nThe `oci-layout` format will fetch the image (or images) and write it to disk according to the\n[OCI Image Layout Specification](https://github.com/opencontainers/image-spec/blob/main/image-layout.md).\n\nIn this format, the resource will produce the following files:\n\n* `./oci/index.json`\n* `./oci/oci-layout`\n* `./oci/blobs/sha256/aabbccdd...`\n* `./oci/blobs/sha256/ffeeddcc...`\n* `./oci/single-image-digest`: this is written only when the original digest specifies a legacy image,\n  rather than an image index. It is in the format `sha256:xxx`\n\nThis format supports images with builds for different architectures, and is suitable for a corresponding\n`put` step, where the resultant put image will have the same digest as the one originally fetched\n(useful for mirroring use-cases).\n\n### `put` Step (`out` script): push and tag an image\n\nPushes an image to the registry as the specified tags.\n\nThe currently encouraged way to build these images is by using the\n[`oci-build-task`](https://github.com/vito/oci-build-task).\n\nTags may be specified in multiple ways:\n\n* With `tag` configured in `source`, the configured tag will always be pushed.\n* With `version` given in `params`, the image will be pushed using the version\n  number as a tag, optionally with a `variant` suffix (configured in `source`).\n* With `additional_tags` given in `params`, the image will be pushed as each\n  tag listed in the file (whitespace separated). Only those tags are pushed, e.g.\n  the default `latest` isn't included.\n\n#### `put` Steps `params`\n\n\u003ctable\u003e\n\u003cthead\u003e\n  \u003ctr\u003e\n    \u003cth\u003eParameter\u003c/th\u003e\n    \u003cth\u003eDescription\u003c/th\u003e\n  \u003c/tr\u003e\n\u003c/thead\u003e\n\u003ctbody\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ccode\u003eimage\u003c/code\u003e \u003cem\u003e(Required)\u003c/em\u003e\u003c/td\u003e\n    \u003ctd\u003e\n    Can be the path to the \u003ccode\u003edocker\u003c/code\u003e image tarball (e.g. \u003ccode\u003emy-image/image.tar\u003c/code\u003e)\n    or the path to the \u003ccode\u003eoci\u003c/code\u003e image tarball (e.g. \u003ccode\u003emy-image/image\u003c/code\u003e)\n    or the path to an \u003ca href=\"https://github.com/opencontainers/image-spec/blob/main/image-layout.md\"\u003eOCI image layout\u003c/a\u003e (e.g. \u003ccode\u003emy-image/oci\u003c/code\u003e).\n    Expanded with \u003ca href=\"https://golang.org/pkg/path/filepath/#Glob\"\u003e\u003ccode\u003efilepath.Glob\u003c/code\u003e\u003c/a\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ccode\u003eversion\u003c/code\u003e \u003cem\u003e(Optional)\u003c/em\u003e\u003c/td\u003e\n    \u003ctd\u003e\n    A version number to use as a tag.\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ccode\u003ebump_aliases\u003c/code\u003e \u003cem\u003e(Optional)\u003cbr\u003eDefault: false\u003c/em\u003e\u003c/td\u003e\n    \u003ctd\u003e\n    When set to \u003ccode\u003etrue\u003c/code\u003e and \u003ccode\u003eversion\u003c/code\u003e is specified,\n    automatically bump alias tags for the version.\n    For example, when pushing version \u003ccode\u003e1.2.3\u003c/code\u003e, push the same image\n    to the following tags:\n    \u003cul\u003e\n      \u003cli\u003e\u003ccode\u003e1.2\u003c/code\u003e, if 1.2.3 is the latest version of 1.2.x.\u003c/li\u003e\n      \u003cli\u003e\u003ccode\u003e1\u003c/code\u003e, if 1.2.3 is the latest version of 1.x.\u003c/li\u003e\n      \u003cli\u003e\u003ccode\u003elatest\u003c/code\u003e, if 1.2.3 is the latest version overall.\u003c/li\u003e\n    \u003c/ul\u003e\n    If \u003ccode\u003evariant\u003c/code\u003e is configured as \u003ccode\u003efoo\u003c/code\u003e, push the same\n    image to the following tags:\n    \u003cul\u003e\n    \u003cli\u003e\u003ccode\u003e1.2-foo\u003c/code\u003e, if 1.2.3 is the latest version of 1.2.x with \u003ccode\u003efoo\u003c/code\u003e.\u003c/li\u003e\n    \u003cli\u003e\u003ccode\u003e1-foo\u003c/code\u003e, if 1.2.3 is the latest version of 1.x with \u003ccode\u003efoo\u003c/code\u003e.\u003c/li\u003e\n    \u003cli\u003e\u003ccode\u003efoo\u003c/code\u003e, if 1.2.3 is the latest version overall for \u003ccode\u003efoo\u003c/code\u003e.\u003c/li\u003e\n    \u003c/ul\u003e\n    Determining which tags to bump is done by comparing to the existing tags\n    that exist on the registry.\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ccode\u003eadditional_tags\u003c/code\u003e \u003cem\u003e(Optional)\u003c/em\u003e\u003c/td\u003e\n    \u003ctd\u003e\n    The path to a file with whitespace-separated list of tag values to tag the\n    image with (in addition to the tag configured in \u003ccode\u003esource\u003c/code\u003e,\n    but not the default `latest` tag if no tag is configured).\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ccode\u003etag_prefix\u003c/code\u003e \u003cem\u003e(Optional)\u003c/em\u003e\u003c/td\u003e\n    \u003ctd\u003e\n    A string that will be prefixed to the tags from \u003ccode\u003eadditional_tags\u003c/code\u003e.\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/tbody\u003e\n\u003c/table\u003e\n\n### Use in tasks\n\nImages used as\n[image resources](https://concourse-ci.org/tasks.html#schema.task.image_resource)\nin tasks are called\n[anonymous resources](https://concourse-ci.org/tasks.html#schema.anonymous_resource).\nAnonymous resources can specify\n[a version](https://concourse-ci.org/tasks.html#schema.anonymous_resource.version),\nwhich is the image digest. For example:\n\n\n```\nimage_resource:\n  type: docker-image\n  source:\n    repository: golang\n  version:\n    digest: 'sha256:5f640aeb8b78e9876546a9d06b928d2ad0c6e51900bcba10ff4e12dc57f6f265'\n```\n\nThis is useful when the registry image does not have tags, or when the tags are\ngoing to be re-used.\n\n## Development\n\n### Prerequisites\n\n* golang is *required* - version 1.16.x or above is required for go mod to work\n* docker is *required* - version 19.03.x and above (`buildx` is required)\n\n### Running the tests\n\nThe tests have been embedded with the `Dockerfile`; ensuring that the testing\nenvironment is consistent across any `docker` enabled platform. When the docker\nimage builds, the test are run inside the docker container, on failure they\nwill stop the build.\n\nRun the tests with the following commands:\n\n```sh\ndocker build -t registry-image-resource --target tests .\n```\n\n#### Integration tests\n\nThe integration requires 3 docker repos: one private dockerhub repo, one public\ndockerhub repo, and one GCR repo. The `docker build` step requires setting\n`--build-args` so the integration will run.\n\nRun the tests with the following command:\n\n```sh\ndocker build . -t registry-image-resource --target tests \\\n  --build-arg DOCKER_PRIVATE_USERNAME=\"some-username\" \\\n  --build-arg DOCKER_PRIVATE_PASSWORD=\"some-password\" \\\n  --build-arg DOCKER_PRIVATE_REPO=\"some/repo\" \\\n  --build-arg DOCKER_PUSH_USERNAME=\"some-username\" \\\n  --build-arg DOCKER_PUSH_PASSWORD=\"some-password\" \\\n  --build-arg DOCKER_PUSH_REPO=\"some/repo\"\n```\n\nNote that you may omit any of the repo credentials in order to skip those\nintegration tests.\n\n### Contributing\n\nPlease make all pull requests to the `master` branch and ensure tests pass\nlocally.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fconcourse%2Fregistry-image-resource","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fconcourse%2Fregistry-image-resource","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fconcourse%2Fregistry-image-resource/lists"}