https://github.com/guibranco/github-artifact-lock-action
🔐 :octocat: Step-level locking in GitHub Actions using artifact-based mutexes — serialize workflow steps across jobs or PRs with no external services.
https://github.com/guibranco/github-artifact-lock-action
actions artifacts concurrency gh-actions github lock locking mutex semaphore step workflow
Last synced: 6 months ago
JSON representation
🔐 :octocat: Step-level locking in GitHub Actions using artifact-based mutexes — serialize workflow steps across jobs or PRs with no external services.
- Host: GitHub
- URL: https://github.com/guibranco/github-artifact-lock-action
- Owner: guibranco
- License: mit
- Created: 2025-04-23T16:14:53.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2025-04-25T11:48:25.000Z (6 months ago)
- Last Synced: 2025-04-27T01:13:46.287Z (6 months ago)
- Topics: actions, artifacts, concurrency, gh-actions, github, lock, locking, mutex, semaphore, step, workflow
- Homepage: http://guilherme.stracini.com.br/github-artifact-lock-action/
- Size: 22.5 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# GitHub Artifact Lock Action
[](https://github.com/guibranco/github-artifact-lock-action)
[](https://github.com/guibranco/github-artifact-lock-action)
[](https://github.com/guibranco/github-artifact-lock-action)
[](https://wakatime.com/badge/github/guibranco/github-artifact-lock-action)
## 📋 Overview
A reusable composite GitHub Action to implement a **step-level mutex lock** using GitHub Artifacts as the locking mechanism. This action enables serialized access to shared resources (like test environments, deployment targets, or external systems) across parallel workflows or pull requests.
## 🚀 Features
- 🔒 **Lock Acquisition**: Securely acquire locks before accessing shared resources
- 🔓 **Automatic Release**: Release locks reliably when operations complete
- ⏱️ **Configurable Timing**: Customize wait times and retry attempts
- 🌐 **Zero Dependencies**: Uses GitHub-native APIs only—no external services required
- 🛡️ **Failure Handling**: Ensures locks are released even when workflows fail
- 📊 **Workflow-Agnostic**: Works across different workflows and repositories
## 💡 When To Use
- Running integration tests that require exclusive access to test environments
- Managing deployments to shared staging environments
- Controlling access to external rate-limited APIs
- Preventing race conditions when multiple workflows update shared resources
- Implementing sequential processing when parallel execution isn't safe
## 📦 Installation
Add this action to your workflow YAML files. No additional setup required!
## ⚙️ Inputs
| Input | Description | Required | Default |
|-------|-------------|:--------:|---------|
| `lock-name` | Unique identifier for the lock (artifact name) | No | `test-lock` |
| `wait-seconds` | Wait time between retry attempts (in seconds) | No | `10` |
| `max-attempts` | Maximum number of retry attempts before failing | No | `30` |
## 📤 Outputs
This action doesn't provide explicit outputs, but creates and removes artifacts that serve as locks.
## 🧪 Usage Examples
### Basic Usage
```yaml
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Acquire test lock 🔐
uses: guibranco/github-artifact-lock-action@v1
with:
lock-name: test-lock
- name: Run tests 🧪
run: echo "Tests running safely..."
- name: Release test lock 🔓
if: always() # Important: ensures lock release even on failure
uses: guibranco/github-artifact-lock-action/release-lock@v1
with:
lock-name: test-lock
```
### Advanced Configuration
```yaml
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Acquire deployment lock 🔐
uses: guibranco/github-artifact-lock-action@v1
with:
lock-name: staging-environment-lock
wait-seconds: 30
max-attempts: 20
- name: Deploy to staging 🚀
run: ./deploy.sh --env staging
- name: Release deployment lock 🔓
if: always()
uses: guibranco/github-artifact-lock-action/release-lock@v1
with:
lock-name: staging-environment-lock
```
### Multiple Locks
```yaml
jobs:
integration:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Acquire database lock 🔐
uses: guibranco/github-artifact-lock-action@v1
with:
lock-name: db-lock
- name: Acquire API lock 🔐
uses: guibranco/github-artifact-lock-action@v1
with:
lock-name: api-lock
- name: Run integration tests 🧪
run: npm run integration-tests
- name: Release API lock 🔓
if: always()
uses: guibranco/github-artifact-lock-action/release-lock@v1
with:
lock-name: api-lock
- name: Release database lock 🔓
if: always()
uses: guibranco/github-artifact-lock-action/release-lock@v1
with:
lock-name: db-lock
```
## 🛠️ How It Works
The action creates a locking mechanism by leveraging GitHub Artifacts storage:
1. **Check**: Before executing a critical step, it checks for an existing GitHub Artifact named `lock-name`
2. **Wait**: If the lock artifact exists, another workflow is using the resource, so this workflow waits
3. **Retry**: The action retries periodically until the lock is free or `max-attempts` is reached
4. **Acquire**: Once free, it uploads a small placeholder artifact with the `lock-name` to claim the lock
5. **Execute**: Your workflow steps run with exclusive access to the resource
6. **Release**: The release-lock action removes the artifact, freeing the resource for other workflows
## 🔄 Integration with Other Actions
This action works well with:
- Deployment actions like `actions/deploy-pages`
- Testing frameworks
- Database migration tools
- Any workflow requiring resource coordination
## 🐛 Troubleshooting
### Common Issues
- **Lock never releases**: Ensure the release step has `if: always()` to run even when prior steps fail
- **Timeouts**: Adjust `wait-seconds` and `max-attempts` for longer-running operations
- **Permissions**: Ensure workflow has sufficient permissions to read/write artifacts
### Debugging
Enable GitHub Actions debug logging by setting a secret named `ACTIONS_STEP_DEBUG` to `true`.
## 🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## 📜 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 👏 Acknowledgments
- Inspired by the need for coordinating concurrent GitHub workflows
- Thanks to all contributors who helped improve this action