{"id":13438439,"url":"https://github.com/concourse/git-resource","last_synced_at":"2025-05-15T13:06:38.860Z","repository":{"id":21008496,"uuid":"24299150","full_name":"concourse/git-resource","owner":"concourse","description":"tracks commits in a branch of a Git repository","archived":false,"fork":false,"pushed_at":"2025-05-13T17:09:37.000Z","size":518,"stargazers_count":200,"open_issues_count":96,"forks_count":292,"subscribers_count":34,"default_branch":"master","last_synced_at":"2025-05-13T18:26:00.789Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Shell","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":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2014-09-21T18:16:16.000Z","updated_at":"2025-05-13T17:09:40.000Z","dependencies_parsed_at":"2024-03-16T22:40:28.939Z","dependency_job_id":"b35425b2-106c-40ee-9d4e-c0f53e6b4aea","html_url":"https://github.com/concourse/git-resource","commit_stats":null,"previous_names":[],"tags_count":42,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/concourse%2Fgit-resource","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/concourse%2Fgit-resource/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/concourse%2Fgit-resource/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/concourse%2Fgit-resource/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/concourse","download_url":"https://codeload.github.com/concourse/git-resource/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254346624,"owners_count":22055808,"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:05.541Z","updated_at":"2025-05-15T13:06:38.802Z","avatar_url":"https://github.com/concourse.png","language":"Shell","funding_links":[],"categories":["HarmonyOS"],"sub_categories":["Windows Manager"],"readme":"# Git Resource\n\nTracks the commits in a [git](http://git-scm.com/) repository.\n\n## Source Configuration\n\n* `uri`: *Required.* The location of the repository.\n\n* `branch`: The branch to track. This is *optional* if the resource is only\n   used in `get` steps; however, it is *required* when used in a `put` step.\n   If unset, `get` steps will checkout the repository's default branch;\n   usually `master` but [could be different](https://help.github.com/articles/setting-the-default-branch/).\n\n* `private_key`: *Optional.* Private key to use when pulling/pushing.\n    Example:\n\n    ```yaml\n    private_key: |\n      -----BEGIN RSA PRIVATE KEY-----\n      MIIEowIBAAKCAQEAtCS10/f7W7lkQaSgD/mVeaSOvSF9ql4hf/zfMwfVGgHWjj+W\n      \u003cLots more text\u003e\n      DWiJL+OFeg9kawcUL6hQ8JeXPhlImG6RTUffma9+iGQyyBMCGd1l\n      -----END RSA PRIVATE KEY-----\n    ```\n\n* `private_key_user`: *Optional.* Enables setting User in the ssh config.\n\n* `private_key_passphrase`: *Optional.* To unlock `private_key` if it is protected by a passphrase.\n\n* `forward_agent`: *Optional* Enables ForwardAgent SSH option when set to true. Useful when using proxy/jump hosts. Defaults to false.\n\n* `username`: *Optional.* Username for HTTP(S) auth when pulling/pushing.\n  This is needed when only HTTP/HTTPS protocol for git is available (which does not support private key auth)\n  and auth is required.\n\n* `password`: *Optional.* Password for HTTP(S) auth when pulling/pushing.\n\n* `paths`: *Optional.* If specified (as a list of glob patterns), only changes\n  to the specified files will yield new versions from `check`.\n\n* `ignore_paths`: *Optional.* The inverse of `paths`; changes to the specified\n  files are ignored.\n\n  Note that if you want to push commits that change these files via a `put`,\n  the commit will still be \"detected\", as [`check` and `put` both introduce\n  versions](https://github.com/concourse/concourse/issues/534).\n  To avoid this you should define a second resource that you use for commits\n  that change files that you don't want to feed back into your pipeline - think\n  of one as read-only (with `ignore_paths`) and one as write-only (which\n  shouldn't need it).\n\n* `skip_ssl_verification`: *Optional.* Skips git ssl verification by exporting\n  `GIT_SSL_NO_VERIFY=true`.\n\n* `tag_filter`: *Optional.* If specified, the resource will only detect commits\n  that have a tag matching the expression that have been made against\n  the `branch`. Patterns are [glob(7)](http://man7.org/linux/man-pages/man7/glob.7.html)\n  compatible (as in, bash compatible).\n\n* `tag_regex`: *Optional.* If specified, the resource will only detect commits\n  that have a tag matching the expression that have been made against\n  the `branch`. Patterns are [grep](https://www.gnu.org/software/grep/manual/grep.html)\n  compatible (extended matching enabled, matches entire lines only). Ignored if\n  `tag_filter` is also specified.\n\n* `fetch_tags`: *Optional.* If `true` the flag `--tags` will be used to fetch\n  all tags in the repository. If `false` no tags will be fetched.\n\n* `submodule_credentials`: *Optional.* List of credentials for HTTP(s) or SSH auth when pulling git submodules which are not stored in the same git server as the container repository or are protected by a different private key.\n  * http(s) credentials:\n    * `host` : The host to connect too. Note that `host` is specified with no protocol extensions.\n    * `username` : Username for HTTP(S) auth when pulling submodule.\n    * `password` : Password for HTTP(S) auth when pulling submodule.\n  * ssh credentials:\n    * `url` : Submodule url, as specified in the `.gitmodule` file. Support full or relative ssh url.\n    * `private_key` : Private key for SSH auth when pulling submodule.\n    * `private_key_passphrase` : *Optional.* To unlock `private_key` if it is protected by a passphrase.\n  * example:\n    ```yaml\n    submodule_credentials:\n      # http(s) credentials\n    - host: github.com\n      username: git-user\n      password: git-password\n      # ssh credentials\n    - url: git@github.com:org-name/repo-name.git\n      private_key: |\n        -----BEGIN RSA PRIVATE KEY-----\n        MIIEowIBAAKCAQEAtCS10/f7W7lkQaSgD/mVeaSOvSF9ql4hf/zfMwfVGgHWjj+W\n        \u003cLots more text\u003e\n        DWiJL+OFeg9kawcUL6hQ8JeXPhlImG6RTUffma9+iGQyyBMCGd1l\n        -----END RSA PRIVATE KEY-----\n      private_key_passphrase: ssh-passphrase # (optionnal)\n      # ssh credentials with relative url\n    - url: ../org-name/repo-name.git\n      private_key: |\n        -----BEGIN RSA PRIVATE KEY-----\n        MIIEowIBAAKCAQEAtCS10/f7W7lkQaSgD/mVeaSOvSF9ql4hf/zfMwfVGgHWjj+W\n        \u003cLots more text\u003e\n        DWiJL+OFeg9kawcUL6hQ8JeXPhlImG6RTUffma9+iGQyyBMCGd1l\n        -----END RSA PRIVATE KEY-----\n      private_key_passphrase: ssh-passphrase # (optionnal)\n    ```\n\n* `git_config`: *Optional.* If specified as (list of pairs `name` and `value`)\n  it will configure git global options, setting each name with each value.\n\n  This can be useful to set options like `credential.helper` or similar.\n\n  See the [`git-config(1)` manual page](https://www.kernel.org/pub/software/scm/git/docs/git-config.html)\n  for more information and documentation of existing git options.\n\n* `disable_ci_skip`: *Optional.* Allows for commits that have been labeled with `[ci skip]` or `[skip ci]`\n   previously to be discovered by the resource.\n\n* `commit_verification_keys`: *Optional.* Array of GPG public keys that the\n  resource will check against to verify the commit (details below).\n\n* `commit_verification_key_ids`: *Optional.* Array of GPG public key ids that\n  the resource will check against to verify the commit (details below). The\n  corresponding keys will be fetched from the key server specified in\n  `gpg_keyserver`. The ids can be short id, long id or fingerprint.\n\n* `gpg_keyserver`: *Optional.* GPG keyserver to download the public keys from.\n  Defaults to `hkp://keyserver.ubuntu.com/`.\n\n* `git_crypt_key`: *Optional.* Base64 encoded\n  [git-crypt](https://github.com/AGWA/git-crypt) key. Setting this will\n  unlock / decrypt the repository with `git-crypt`. To get the key simply\n  execute `git-crypt export-key -- - | base64` in an encrypted repository.\n\n* `https_tunnel`: *Optional.* Information about an HTTPS proxy that will be used to tunnel SSH-based git commands over.\n  Has the following sub-properties:\n  * `proxy_host`: *Required.* The host name or IP of the proxy server\n  * `proxy_port`: *Required.* The proxy server's listening port\n  * `proxy_user`: *Optional.* If the proxy requires authentication, use this username\n  * `proxy_password`: *Optional.* If the proxy requires authenticate,\n      use this password\n\n* `commit_filter`: *Optional.* Object containing commit message filters\n  * `exclude`: *Optional.* Array containing strings that should\n    cause a commit to be skipped\n  * `exclude_all_match`: *Optional.* Boolean wheater it should match all the exclude filters \"AND\", default: false\n  * `include`: *Optional.* Array containing strings that\n    *MUST* be included in commit messages for the commit to not be\n    skipped\n  * `include_all_match`: *Optional.* Boolean wheater it should match all the include filters \"AND\", default: false\n\n  **Note**: *You must escape any regex sensitive characters, since the string is used as a regex filter.*  \n  For example, using `[skip deploy]` or `[deploy skip]` to skip non-deployment related commits in a deployment pipeline:\n\n  ```yaml\n  commit_filter:\n    exclude: [\"\\\\[skip deploy\\\\]\", \"\\\\[deploy skip\\\\]\"]\n  ```\n\n* `version_depth`: *Optional.* The number of versions to return when performing a check\n\n* `search_remote_refs`: *Optional.* True to search remote refs for the input version when checking out during the get step.\n    This can be useful during the `get` step after a `put` step for unconventional workflows. One example workflow is the\n    `refs/for/\u003cbranch\u003e` workflow used by gerrit which 'magically' creates a `refs/changes/nnn` reference instead\n    of the straight forward `refs/for/\u003cbranch\u003e` reference that a git remote would usually create.\n    See also `out params.refs_prefix`.\n\n### Example\n\nResource configuration for a private repo with an HTTPS proxy:\n\n``` yaml\nresources:\n- name: source-code\n  type: git\n  source:\n    uri: git@github.com:concourse/git-resource.git\n    branch: master\n    private_key: |\n      -----BEGIN RSA PRIVATE KEY-----\n      MIIEowIBAAKCAQEAtCS10/f7W7lkQaSgD/mVeaSOvSF9ql4hf/zfMwfVGgHWjj+W\n      \u003cLots more text\u003e\n      DWiJL+OFeg9kawcUL6hQ8JeXPhlImG6RTUffma9+iGQyyBMCGd1l\n      -----END RSA PRIVATE KEY-----\n    git_config:\n    - name: core.bigFileThreshold\n      value: 10m\n    disable_ci_skip: true\n    git_crypt_key: AEdJVEN...snip...AAA==\n    https_tunnel:\n      proxy_host: proxy-server.mycorp.com\n      proxy_port: 3128\n      proxy_user: myuser\n      proxy_password: myverysecurepassword\n```\n\nResource configuration for a private repo with a private submodule from different git server:\n\n``` yaml\nresources:\n- name: source-code\n  type: git\n  source:\n    uri: git@github.com:concourse/git-resource.git\n    branch: master\n    submodule_credentials:\n    - host: some.other.git.server\n      username: user\n      password: verysecurepassword\n    private_key: |\n      -----BEGIN RSA PRIVATE KEY-----\n      MIIEowIBAAKCAQEAtCS10/f7W7lkQaSgD/mVeaSOvSF9ql4hf/zfMwfVGgHWjj+W\n      \u003cLots more text\u003e\n      DWiJL+OFeg9kawcUL6hQ8JeXPhlImG6RTUffma9+iGQyyBMCGd1l\n      -----END RSA PRIVATE KEY-----\n```\n\nFetching a repo with only 100 commits of history:\n\n``` yaml\n- get: source-code\n  params: {depth: 100}\n```\n\nPushing local commits to the repo:\n\n``` yaml\n- get: some-other-repo\n- put: source-code\n  params: {repository: some-other-repo}\n```\n\nFetching a repo pinned to a specific commit:\n\n``` yaml\nresources:\n- name: source-code\n  type: git\n  source:\n    uri: git@github.com:concourse/git-resource.git\n    branch: master\n  version:\n    ref: commit-sha\n```\n\n## Behavior\n\n### `check`: Check for new commits\n\nThe repository is cloned (or pulled if already present), and any commits\nfrom the given version on are returned. If no version is given, the ref\nfor `HEAD` is returned.\n\nAny commits that contain the string `[ci skip]` will be ignored. This\nallows you to commit to your repository without triggering a new version.\n\n### `in`: Clone the repository, at the given ref\n\nClones the repository to the destination, and locks it down to a given ref.\nIt will return the same given ref as version.\n\n`git-crypt` encrypted repositories will automatically be decrypted, when the\ncorrect key is provided set in `git_crypt_key`.\n\n#### Parameters\n\n* `depth`: *Optional.* If a positive integer is given, *shallow* clone the\n  repository using the `--depth` option. To prevent newer commits that do\n  not pass a `paths` filter test from skewing the cloned history away from\n  `version.ref`, this resource will automatically deepen the clone until\n  `version.ref` is found again. It will deepen with exponentially increasing steps\n  until a maximum of 127 + `depth` commits or else resort to unshallow the repository.\n\n* `fetch_tags`: *Optional.* If `true` the flag `--tags` will be used to fetch\n  all tags in the repository. If `false` no tags will be fetched.\n\n  Will override `fetch_tags` source configuration if defined.\n\n* `submodules`: *Optional.* If `none`, submodules will not be\n  fetched. If specified as a list of paths, only the given paths will be\n  fetched. If not specified, or if `all` is explicitly specified, all\n  submodules are fetched.\n\n* `submodule_recursive`: *Optional.* If `false`, a flat submodules checkout is performed. If not specified, or if `true` is explicitly specified, a recursive checkout is performed.\n\n* `submodule_remote`: *Optional.* If `true`, the submodules are checked out for the specified remote branch specified in the `.gitmodules` file of the repository. If not specified, or if `false` is explicitly specified, the tracked sub-module revision of the repository is used to check out the submodules.\n\n* `disable_git_lfs`: *Optional.* If `true`, will not fetch Git LFS files.\n\n* `clean_tags`: *Optional.* If `true` all incoming tags will be deleted. This\n  is useful if you want to push tags, but have reasonable doubts that the tags\n  cached with the resource are outdated. The default value is `false`.\n\n* `short_ref_format`: *Optional.* When populating `.git/short_ref` use this `printf` format. Defaults to `%s`.\n\n* `timestamp_format`: *Optional.* When populating `.git/commit_timestamp` use this options to pass to [`git log --date`](https://git-scm.com/docs/git-log#Documentation/git-log.txt---dateltformatgt). Defaults to `iso8601`.\n\n* `describe_ref_options`: *Optional.* When populating `.git/describe_ref` use this options to call [`git describe`](https://git-scm.com/docs/git-describe). Defaults to `--always --dirty --broken`.\n\n#### GPG signature verification\n\nIf `commit_verification_keys` or `commit_verification_key_ids` is specified in\nthe source configuration, it will additionally verify that the resulting commit\nhas been GPG signed by one of the specified keys. It will error if this is not\nthe case.\n\n#### Additional files populated\n\n* `.git/committer`: For committer notification on failed builds.\n This special file `.git/committer` which is populated with the email address\n of the author of the last commit. This can be used together with  an email\n resource like [mdomke/concourse-email-resource](https://github.com/mdomke/concourse-email-resource)\n to notify the committer in an on_failure step.\n\n* `.git/ref`: Version reference detected and checked out. It will usually contain\n the commit SHA-1 ref, but also the detected tag name when using `tag_filter` or\n `tag_regex`.\n\n* `.git/branch`: Name of the original branch that was cloned.\n\n* `.git/short_ref`: Short (first seven characters) of the `.git/ref`. Can be templated with `short_ref_format` parameter.\n\n* `.git/commit_message`: For publishing the Git commit message on successful builds.\n\n* `.git/commit_timestamp`: For tagging builds with a timestamp.\n\n* `.git/describe_ref`: Version reference detected and checked out. Can be templated with `describe_ref_options` parameter.\n By default, it will contain the `\u003clatest annoted git tag\u003e-\u003cthe number of commit since the tag\u003e-g\u003cshort_ref\u003e` (eg. `v1.6.2-1-g13dfd7b`).\n If the repo was never tagged before, this falls back to a short commit SHA-1 ref.\n\n### `out`: Push to a repository\n\nPush the checked-out reference to the source's URI and branch. All tags are\nalso pushed to the source. If a fast-forward for the branch is not possible\nand the `rebase` parameter is not provided, the push will fail.\n\n#### Parameters\n\n* `repository`: *Required.* The path of the repository to push to the source.\n\n* `rebase`: *Optional.* If pushing fails with non-fast-forward, continuously\n  attempt rebasing and pushing.\n\n* `merge`: *Optional.* If pushing fails with non-fast-forward, continuously\n  attempt to merge remote to local before pushing. Only one of `merge` or\n  `rebase` can be provided, but not both.\n\n* `returning`: *Optional.* When passing the `merge` flag, specify whether the\n  merge commit or the original, unmerged commit should be passed as the output\n  ref. Options are `merged` and `unmerged`. Defaults to `merged`.\n\n* `tag`: *Optional.* If this is set then HEAD will be tagged. The value should be\n  a path to a file containing the name of the tag.\n\n* `only_tag`: *Optional.* When set to 'true' push only the tags of a repo.\n\n* `tag_prefix`: *Optional.* If specified, the tag read from the file will be\nprepended with this string. This is useful for adding `v` in front of\nversion numbers.\n\n* `force`: *Optional.* When set to 'true' this will force the branch to be\npushed regardless of the upstream state.\n\n* `annotate`: *Optional.* If specified the tag will be an\n  [annotated](https://git-scm.com/book/en/v2/Git-Basics-Tagging#Annotated-Tags)\n  tag rather than a\n  [lightweight](https://git-scm.com/book/en/v2/Git-Basics-Tagging#Lightweight-Tags)\n  tag. The value should be a path to a file containing the annotation message.\n\n* `notes`: *Optional.* If this is set then notes will be added to HEAD to the\n  `refs/notes/commits` ref. The value should be a path to a file containing the notes.\n\n* `branch`: *Optional.* The branch to push commits.\n\n  Note that the version produced by the `put` step will be picked up by subsequent `get` steps\n  even if the `branch` differs from the `branch` specified in the source.\n  To avoid this, you should use two resources of read-only and write-only.\n\n* `refs_prefix`: *Optional.* Allows pushing to refs other than heads. Defaults to `refs/heads`.\n\n  Useful when paired with `source.search_remote_refs` in cases where the git remote\n  renames the ref you pushed.\n\n## Development\n\n### Prerequisites\n\n* golang is *required* - version 1.9.x is tested; earlier versions may also\n  work.\n* docker is *required* - version 17.06.x is tested; earlier versions may also\n  work.\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 command:\n\n```sh\ndocker build -t git-resource --target tests --build-arg base_image=paketobuildpacks/run-jammy-base:latest .\n\n```\n\n#### Note about the integration tests\n\nIf you want to run the integration tests, a bit more work is required. You will require\nan actual git repo to which you can push and pull, configured for SSH access. To do this,\nadd two files to `integration-tests/ssh` (note that names **are** important):\n\n* `test_key`: This is the private key used to authenticate against your repo.\n* `test_repo`: This file contains one line of the form `test_repo_url[#test_branch]`.\n  If the branch is not specified, it defaults to `master`. For example,\n  `git@github.com:concourse-git-tester/git-resource-integration-tests.git` or\n  `git@github.com:concourse-git-tester/git-resource-integration-tests.git#testing`\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%2Fgit-resource","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fconcourse%2Fgit-resource","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fconcourse%2Fgit-resource/lists"}