{"id":23613660,"url":"https://github.com/freckle/aws-s3-lock-action","last_synced_at":"2026-05-30T11:01:14.691Z","repository":{"id":204927255,"uuid":"712894212","full_name":"freckle/aws-s3-lock-action","owner":"freckle","description":null,"archived":false,"fork":false,"pushed_at":"2026-05-23T13:27:13.000Z","size":3588,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-05-23T15:20:40.701Z","etag":null,"topics":["ghvm-managed"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/freckle.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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-11-01T12:27:59.000Z","updated_at":"2026-05-23T13:26:26.000Z","dependencies_parsed_at":"2023-12-28T01:56:08.289Z","dependency_job_id":"936dbc89-9c19-4b77-8121-c8cb66bd3e19","html_url":"https://github.com/freckle/aws-s3-lock-action","commit_stats":null,"previous_names":["freckle/aws-s3-lock-action"],"tags_count":21,"template":false,"template_full_name":"freckle/typescript-action-template","purl":"pkg:github/freckle/aws-s3-lock-action","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/freckle%2Faws-s3-lock-action","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/freckle%2Faws-s3-lock-action/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/freckle%2Faws-s3-lock-action/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/freckle%2Faws-s3-lock-action/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/freckle","download_url":"https://codeload.github.com/freckle/aws-s3-lock-action/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/freckle%2Faws-s3-lock-action/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33689564,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-30T02:00:06.278Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["ghvm-managed"],"created_at":"2024-12-27T17:18:38.217Z","updated_at":"2026-05-30T11:01:14.649Z","avatar_url":"https://github.com/freckle.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AWS S3 Lock\n\nWait for, acquire, and release a distributed lock via S3 storage.\n\n## Usage\n\n```yaml\n- uses: aws-actions/configure-aws-credentials@v4\n  with:\n    # ...\n\n# This blocks until the lock is acquired, or errors if timeout is reached\n- uses: freckle/aws-s3-lock-action@v1\n  with:\n    # Required\n    bucket: an-existing-s3-bucket\n\n    # Optional, defaults shown\n    # name: {workflow}/{job}\n    # expires: 15m\n    # timeout: {matches expires}\n    # timeout-poll: 5s\n    # context: \"{workflow} #{run}\"\n\n- run: echo \"Lock held, do work here\"\n```\n\n![](./screenshot.png)\n\nThe lock is released (the S3 object deleted) in our Post step, which provides a\npretty robust guarantee of release. Expired locks are ignored (not deleted), so\nit's recommended you put a Lifecyle policy on the Bucket to clean them up after\nsome time.\n\n## Usage (Multi-Job)\n\n```yaml\njobs:\n  acquire-lock:\n    # ...\n\n    steps:\n      - uses: aws-actions/configure-aws-credentials@v4\n        with:\n          # ...\n\n      # This blocks until the lock is acquired, or errors if timeout is reached\n      - id: lock\n        uses: freckle/aws-s3-lock-action/acquire@v1\n        with:\n          # Required\n          bucket: an-existing-s3-bucket\n\n          # Optional, defaults shown\n          # name: {workflow}/{job}\n          # expires: 15m\n          # timeout: {matches expires}\n          # timeout-poll: 5s\n          # context: \"{workflow} #{run}\"\n    outputs:\n      key: ${{ steps.lock.outputs.key }}\n\n  work:\n    # ...\n\n    needs:\n      - acquire-lock\n\n    steps:\n      - run: echo \"Lock held, do work here\"\n\n  release:\n    # ...\n\n    if: ${{ always() }}\n\n    needs:\n      - acquire-lock\n      - work\n\n    steps:\n      - uses: aws-actions/configure-aws-credentials@v4\n        with:\n          # ...\n\n      - uses: freckle/aws-s3-lock-action/release@v1\n        with:\n          bucket: an-existing-s3-bucket\n          key: ${{ needs.acquire-lock.outputs.key }}\n```\n\n\u003c!-- action-docs-inputs action=\"action.yml\" --\u003e\n\n## Inputs\n\n| name           | description                                                                                                                           | required | default                                            |\n| -------------- | ------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------------------------------------------------- |\n| `bucket`       | \u003cp\u003eName of an existing S3 bucket to use.\u003c/p\u003e                                                                                          | `true`   | `\"\"`                                               |\n| `name`         | \u003cp\u003eName for the lock object. Include any prefix you want within the bucket. The key will be built as \"name.created.uuid.expires\".\u003c/p\u003e | `false`  | `${{ github.workflow }}/${{ github.job }}`         |\n| `expires`      | \u003cp\u003eHow long before concurrent operations consider this lock expired.\u003c/p\u003e                                                              | `false`  | `15m`                                              |\n| `timeout`      | \u003cp\u003eHow long to wait for the lock to become available. Default matches expires.\u003c/p\u003e                                                    | `false`  | `\"\"`                                               |\n| `timeout-poll` | \u003cp\u003eHow long to wait between attempts for the lock. Default is 5s.\u003c/p\u003e                                                                 | `false`  | `5s`                                               |\n| `context`      | \u003cp\u003eAdditional context to write as the body of the lock file. Concurrent operations waiting on this lock will display it.\u003c/p\u003e          | `false`  | `${{ github.workflow }} #${{ github.run_number }}` |\n\n\u003c!-- action-docs-inputs action=\"action.yml\" --\u003e\n\n\u003c!-- action-docs-outputs action=\"action.yml\" --\u003e\n\n## Outputs\n\n| name          | description                                       |\n| ------------- | ------------------------------------------------- |\n| `key`         | \u003cp\u003eKey of the S3 object representing the lock\u003c/p\u003e |\n| `acquired-at` | \u003cp\u003eTimestamp the lock was acquired\u003c/p\u003e            |\n\n\u003c!-- action-docs-outputs action=\"action.yml\" --\u003e\n\n## Implementation Details\n\n### Algorithm\n\nThis tool implements a version of the locking algorithm described in this\n[StackOverflow answer][answer].\n\n[answer]: https://stackoverflow.com/questions/45222819/can-pseudo-lock-objects-be-used-in-the-amazon-s3-api/75347123#75347123\n\n- Upload a lock object to S3 at `\u003cname\u003e.\u003ccreated\u003e.\u003cuuid\u003e.\u003cexpires\u003e`\n\n  All time values are milliseconds since epoch.\n\n- List all other lock objects (prefix `\u003cname\u003e.`)\n\n  Filter out any expired keys (looking at `expires`) and sort, which implicitly\n  means by `created` then `uuid` as desired.\n\n- If the first one (i.e. oldest) is our own, we've acquired the lock\n- If not, we lost the race; remove our object, wait, and try again\n\n### Ordering Semantics\n\nEach time we attempt to acquire the lock, we create a new key name (e.g.\n`\u003ccreated\u003e` and `\u003cexpires\u003e` both change), this effectively loses our \"place in\nline\" but ensures that expiry is measured from time of acquisition and not time\nof first attempt. There are trade-offs either way, and possible room for\nimprovement, so this is just how we're doing it for now.\n\n### Caveat\n\n**This tool is not meant to be bullet-proof**. We built it for our needs and\naccept that there are simply no strong guarantees in this locking mechanism's\noperation at scale. Your mileage may vary; patches welcome.\n\n## Versioning\n\nVersioned tags will exist, such as `v1.0.0` and `v2.1.1`. Branches will exist\nfor each major version, such as `v1` or `v2` and contain the newest version in\nthat series.\n\n## Release\n\nTo trigger a release (and update the `@v{major}` tag), merge a commit to `main`\nthat follows [Conventional Commits][]. In short,\n\n- `fix:` to trigger a patch release,\n- `feat:` for minor, and\n- `feat!:` and major\n\nWe don't enforce conventional commits generally (though you are free do so),\nit's only required if you want to trigger release.\n\n[conventional commits]: https://www.conventionalcommits.org/en/v1.0.0/#summary\n\n---\n\n[LICENSE](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffreckle%2Faws-s3-lock-action","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffreckle%2Faws-s3-lock-action","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffreckle%2Faws-s3-lock-action/lists"}