This repository serves as a proof-of-concept and reference implementation for configuring Python Semantic Release (PSR) to work with GitHub Protected Branches using Deploy Keys.
It uses Poetry for dependency management and project configuration.
When using Python Semantic Release in a GitHub Actions workflow on a protected branch (e.g., main), the default GITHUB_TOKEN often lacks the permissions to push commits (version bumps) and tags directly to the branch if "Restrict pushes to matching branches" is enabled.
While using a Personal Access Token (PAT) is a common workaround, it is often considered not developer friendly and problematic for automation due to:
- User Dependency: PATs are tied to individual user accounts. If the user leaves or their account is disabled, automation breaks.
- Security Exposure: PATs often grant access to all repositories the user has access to, creating a larger blast radius if compromised.
- Rotation Complexity: Managing rotation for PATs across multiple repositories is tedious and error-prone.
- Accountability: It can be difficult to distinguish between actions taken by the user and the automation.
The solution involves a hybrid approach:
- Git Operations (Pushing Commits/Tags): Use an SSH Deploy Key with write access. This bypasses the standard token restrictions for git pushes.
- Note: We use
webfactory/ssh-agentto forward the SSH key to the Docker container/runner environment, ensuring thegit pushcommands executed by PSR can authenticate successfully.
- Note: We use
- API Operations (Creating Releases): Use the standard GITHUB_TOKEN to authenticate with the GitHub API for creating the Release entry and uploading artifacts.
- Generate an SSH Key Pair:
ssh-keygen -t ed25519 -C "[email protected]:owner/repo.git" -N ""- Important: A subtle difference from the original
sbelloneexample is that forwebfactory/ssh-agentto work properly here, you should use your SSH repository URL as the comment (-C).
- Important: A subtle difference from the original
- Deploy Keys: Add the Public Key to your repository's Settings > Deploy keys. Enable "Allow write access".
- Secrets: Add the Private Key to your repository's Settings > Secrets and variables > Actions as
DEPLOY_KEY.
Configure PSR to ignore the token for push operations (forcing it to use the system's SSH config) and explicitly map the API token.
[tool.semantic_release.remote]
type = "github"
token = { env = "GITHUB_TOKEN" }
ignore_token_for_push = trueYour workflow must:
- Checkout the repository using the
DEPLOY_KEY(sets up the git remote with SSH). - Start the SSH agent with the
DEPLOY_KEY. - Pass the
GITHUB_TOKENto the semantic-release command.
steps:
- name: Checkout Repository
uses: actions/checkout@v4
with:
ssh-key: ${{ secrets.DEPLOY_KEY }}
fetch-depth: 0
- name: Setup SSH Agent
uses: webfactory/[email protected]
with:
ssh-private-key: ${{ secrets.DEPLOY_KEY }}
# ... setup python, poetry ...
- name: Python Semantic Release
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
poetry run semantic-release versionThis configuration addresses the scenario discussed in Python Semantic Release Issue #1343.
The deploy key workaround to bypass branch protection was originally discovered and documented by sbellone/release-workflow-example.