{"id":19259250,"url":"https://github.com/concourse/time-resource","last_synced_at":"2025-05-15T17:06:16.243Z","repository":{"id":18053185,"uuid":"21106406","full_name":"concourse/time-resource","owner":"concourse","description":"a resource for triggering on an interval","archived":false,"fork":false,"pushed_at":"2025-05-13T17:16:43.000Z","size":1261,"stargazers_count":46,"open_issues_count":5,"forks_count":34,"subscribers_count":23,"default_branch":"master","last_synced_at":"2025-05-13T18:31:40.739Z","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":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["taylorsilva"]}},"created_at":"2014-06-22T21:44:07.000Z","updated_at":"2025-05-13T17:16:46.000Z","dependencies_parsed_at":"2024-06-18T20:07:20.214Z","dependency_job_id":"01c7227b-7844-4647-83d0-fadfa3cae680","html_url":"https://github.com/concourse/time-resource","commit_stats":null,"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/concourse%2Ftime-resource","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/concourse%2Ftime-resource/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/concourse%2Ftime-resource/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/concourse%2Ftime-resource/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/concourse","download_url":"https://codeload.github.com/concourse/time-resource/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254384988,"owners_count":22062422,"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-11-09T19:15:51.086Z","updated_at":"2025-05-15T17:06:11.234Z","avatar_url":"https://github.com/concourse.png","language":"Go","funding_links":["https://github.com/sponsors/taylorsilva"],"categories":[],"sub_categories":[],"readme":"# Time Resource\n\nImplements a resource that reports new versions on a configured interval. The\ninterval can be arbitrarily long.\n\nThis resource is built to satisfy \"trigger this build at least once every 5\nminutes,\" not \"trigger this build on the 10th hour of every Sunday.\" That\nlevel of precision is better left to other tools.\n\n## Source Configuration\n\n* `interval`: *Optional.* The interval on which to report new versions. Valid\n  units are: “ns”, “us” (or “µs”), “ms”, “s”, “m”, “h”. Examples: `60s`, `90m`,\n  `1h30m`. If not specified, this resource will generate exactly 1 new version\n  per calendar day on each of the valid `days`.\n\n* `location`: *Optional. Default `UTC`.* The\n  [location](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) in\n  which to interpret `start`, `stop`, and `days`.\n\n  e.g.\n\n  ```\n  location: Africa/Abidjan\n  ```\n\n* `start` and `stop`: *Optional.* Limit the creation of new versions to times\n  on/after `start` and before `stop`. The supported formats for the times are:\n  `3:04 PM`, `3PM`, `3PM`, `15:04`, and `1504`. If a `start` is specified, a\n  `stop` must also be specified, and vice versa. If neither value is specified,\n  both values will default to `00:00` and this resource can generate a new\n  version (based on `interval`) at any time of day.\n\n  e.g.\n\n  ```\n  start: 8:00 PM\n  stop: 9:00 PM\n  ```\n\n  **Deprecation: an offset may be appended, e.g. `+0700` or `-0400`, but you\n  should use `location` instead.**\n\n  To explicitly represent a full calendar day, set `start` and `stop` to\n  the same value.\n\n  e.g.\n\n  ```\n  start: 6:00 AM\n  stop: 6:00 AM\n  ```\n\n  **Note: YAML parsers like PyYAML may parse time values in the 24h format as integers, not strings (e.g. `19:00` is parsed as `1140`). If you pre-process your pipeline configuration with such a parser this might trigger a marshaling error. In that case you can quote your `start` and `stop` values, so they will be correctly treated as string.**\n\n* `days`: *Optional.* Limit the creation of new time versions to the specified\n  day(s). Supported days are: `Sunday`, `Monday`, `Tuesday`, `Wednesday`,\n  `Thursday`, `Friday` and `Saturday`.\n\n  e.g.\n\n  ```\n  days: [Monday, Wednesday]\n  ```\n\n  These can be combined to emit a new version on an interval during a particular\n  time period.\n\n* `initial_version`: *Optional.* When using `start` and `stop` as a trigger for\n  a job, you will be unable to run the job manually until it goes into the\n  configured time range for the first time (manual runs will work once the `time`\n  resource has produced it's first version).\n\n  To get around this issue, there are two approaches:\n     * Use `initial_version: true`, which will produce a new version that is\n       set to the current time, if `check` runs and there isn't already a version\n       specified. **NOTE: This has a downside that if used with `trigger: true`, it will\n       kick off the correlating job when the pipeline is first created, even\n       outside of the specified window**.\n     * Alternatively, once you push a pipeline that utilizes `start` and `stop`, run the\n       following fly command to run the resource check from a previous point\n       in time (see [this issue](https://github.com/concourse/time-resource/issues/24#issuecomment-689422764)\n       for 6.x.x+ or [this issue](https://github.com/concourse/time-resource/issues/11#issuecomment-562385742)\n       for older Concourse versions).\n\n       ```\n       fly -t \u003cyour target\u003e \\\n         check-resource --resource \u003cpipeline\u003e/\u003cyour resource\u003e\n         --from \"time:2000-01-01T00:00:00Z\" # the important part\n       ```\n\n       This has the benefit that it shouldn't trigger that initial job run, but\n       will still allow you to manually run the job if needed.\n\n  e.g.\n\n  ```\n  initial_version: true\n  ```\n\n## Behavior\n\n### `check`: Produce timestamps satisfying the interval.\n\nReturns current version and new version only if it has been longer than `interval` since the\ngiven version, or if there is no version given.\n\n\n### `in`: Report the given time.\n\nFetches the given timestamp. Creates three files:\n1. `input` which contains the request provided by Concourse\n1. `timestamp` which contains the fetched version in the following format: `2006-01-02 15:04:05.999999999 -0700 MST`\n1. `epoch` which contains the fetched version as a Unix epoch Timestamp (integer only)\n\n#### Parameters\n\n*None.*\n\n\n### `out`: Produce the current time.\n\nReturns a version for the current timestamp. This can be used to record the\ntime within a build plan, e.g. after running some long-running task.\n\n#### Parameters\n\n*None.*\n\n\n## Examples\n\n### Periodic trigger\n\n```yaml\nresources:\n- name: 5m\n  type: time\n  source: {interval: 5m}\n\njobs:\n- name: something-every-5m\n  plan:\n  - get: 5m\n    trigger: true\n  - task: something\n    config: # ...\n```\n\n### Trigger once within time range\n\n```yaml\nresources:\n- name: after-midnight\n  type: time\n  source:\n    start: 12:00 AM\n    stop: 1:00 AM\n    location: Asia/Sakhalin\n\njobs:\n- name: something-after-midnight\n  plan:\n  - get: after-midnight\n    trigger: true\n  - task: something\n    config: # ...\n```\n\n### Trigger on an interval within time range\n\n```yaml\nresources:\n- name: 5m-during-midnight-hour\n  type: time\n  source:\n    interval: 5m\n    start: 12:00 AM\n    stop: 1:00 AM\n    location: America/Bahia_Banderas\n\njobs:\n- name: something-every-5m-during-midnight-hour\n  plan:\n  - get: 5m-during-midnight-hour\n    trigger: true\n  - task: something\n    config: # ...\n```\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* go mod is used for dependency management of the golang packages.\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 time-resource --target tests --build-arg base_image=concourse/resource-types-base-image-static:latest .\n```\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%2Ftime-resource","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fconcourse%2Ftime-resource","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fconcourse%2Ftime-resource/lists"}