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
name: test
on: [push, pull_request]
permissions:
actions: write
contents: read
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Acquire test lock π
uses: guibranco/github-artifact-lock-action@v2.0.5
with:
lock-name: test-lock
- name: Run tests π§ͺ
run: echo "Tests running safely..."
- name: Release test lock π
if: always()
uses: guibranco/github-artifact-lock-action/release-lock@v2.0.5
with:
lock-name: test-lock
Advanced Configuration
name: deploy
on: [push]
permissions:
actions: write
contents: read
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Acquire deployment lock π
uses: guibranco/github-artifact-lock-action@v2.0.5
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@v2.0.5
with:
lock-name: staging-environment-lock
Multiple Locks
name: integration
on: [push]
permissions:
actions: write
contents: read
jobs:
integration:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Acquire database lock π
uses: guibranco/github-artifact-lock-action@v2.0.5
with:
lock-name: db-lock
- name: Acquire API lock π
uses: guibranco/github-artifact-lock-action@v2.0.5
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@v2.0.5
with:
lock-name: api-lock
- name: Release database lock π
if: always()
uses: guibranco/github-artifact-lock-action/release-lock@v2.0.5
with:
lock-name: db-lock
π οΈ How It Works
The action creates a locking mechanism by leveraging GitHub Artifacts storage:
- Check: Before executing a critical step, it checks for an existing GitHub Artifact named
lock-name
- Wait: If the lock artifact exists, another workflow is using the resource, so this workflow waits
- Retry: The action retries periodically until the lock is free or
max-attempts
is reached - Acquire: Once free, it uploads a small placeholder artifact with the
lock-name
to claim the lock - Execute: Your workflow steps run with exclusive access to the resource
- 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
andmax-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.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature
) - Commit your changes (
git commit -m 'Add some amazing feature'
) - Push to the branch (
git push origin feature/amazing-feature
) - Open a Pull Request
π License
This project is licensed under the MIT License - see the LICENSE file for details.
π Acknowledgments
- Inspired by the need for coordinating concurrent GitHub workflows
- Thanks to all contributors who helped improve this action