Securefix Action is GitHub Actions to fix code securely.
Securefix Action allows you to fix code securely without sharing a GitHub App private key with strong permissions such as contents:write across GitHub Actions workflows.
You don't need to allow external services to access your code.
It elevates the security of your workflows to the next level.
Furthermore, it's easy to use. You don't need to host a server application. It achieves a server/client architecture using GitHub Actions by unique approach.
See also Release Notes.
- 💪 Increase the developer productivity by fixing code in CI
- 🛡 Secure
- You don't need to pass a GitHub App private key with strong permissions to GitHub Actions workflows on the client side
- You don't need to allow external services to access your code
- You can define custom validation before creating a commit
- Commits are verified (signed)
- 😊 Easy to use
- You can create a commit by one action on the client side
- You don't need to host a server application
- 😉 OSS (MIT License)
Sometimes you want to fix code in CI:
- Format code
- Generate document from code
- etc
In case of public repositories, we strongly recommend autofix.ci. autofix.ci allows you to fix code in CI of pull requests including pull requests from fork repositories securely. autofix.ci is easy to use, and it's free in public repositories. We love it.
autofix.ci is also available in private repositories, but perhaps it's a bit hard to use it in your private repositories for your business.
- It's not free, so you may have to submit a request to your company
- You need to allow the external server of autofix.ci to access your code. Perhaps you can't accept it
- If you don't receive pull requests from fork repositories, the reason to use autofix.ci might not be so string because you can fix code using actions such as commit-action
We think autofix.ci is valuable in private repositories too, but perhaps you can't use it.
If you use fix code in CI, you need to use an access token with contents:write permission.
But if the token is abused, malicious code can be committed.
For instance, an attacker can create a malicious commit to a pull request, and he may be able to approve and merge the pull request.
It's so dangerous.
To prevent such a threat, you should protect personal access tokens and GitHub Apps having strong permissions securely.
One solution is the Client/Server Model. Clients are GitHub Actions workflows that want to fix code. They send a request to the server, then the server fix code. You don't need to pass an access token with strong permissions to clients (GitHub Actions Workflows).
Then how do you build the server? For instance, you would be able to build the server using AWS Lambda, Google Cloud Function, or k8s, and so on. But we don't want to host such a server application.
So we build a server using GitHub Actions workflow by unique approach. You don't need to host a server application.
Securefix Action adopts the Client/Server Model. It uses following GitHub Apps, repositories, and workflows:
- two GitHub Apps
- a Server GitHub App: a GitHub App to create commits
- a Client GitHub App: a GitHub App to send requests to a server workflow
- Repositories
- a Server repository: a repository where a server workflow works
- Client repositories: repositories where client workflows work
- Workflows
- a Server Workflow: Receive requests from client workflows and create commits
- a Client Workflow: Request to fix code to the Server Workflow
- Server: 1 GitHub App, 1 Repository
- Client: 1 GitHub App, N Repositories
- The client workflow uploads fixed files and metadata to GitHub Actions Artifacts
- The client workflow creates an issue label to the server repository (The label is deleted immediately)
- The server workflow is triggered by
label:createdevent - The server workflow downloads fixed files and metadata from GitHub Actions Artifacts
- The server workflow validates the request
- The server workflow pushes a commit to the client repository
Securefix Action uses label event to trigger a server workflow.
Generally repository_dispatch events are used to trigger workflows by API, but they require the permission contents:write.
If we grant contents:write permissions to client workflows, this action has no sense because clients can create commits without this action.
So we looked for alternative events from all events, and we found label event.
Even if the permission is abused, the risk is low.
- Create two repositories from templates demo-server and demo-client
- Create a GitHub App for server
- Create a GitHub App for client
- Create GitHub App private keys
- Add GitHub App's id and private keys to GitHub Secrets and Variables
- Fix the server workflow if necessary
- Fix the client workflow if necessary
- Add a new file
bar.yamlto client' repository and create a pull request
Deactivate Webhook.
Permissions:
contents:write: To create commitsactions:read: To download GitHub Actions Artifacts to fix codepull_requests:write: To notify problems on the server side to pull requestsworkflows:write: Optional. This is required if you want to fix GitHub Actions workflowsissues:write: Optional. This is required if you want to add labels to pull requestsmembers:read: Optional. This is required if you want to request reviews to teams
Installed Repositories: Install the app into the server repository and client repositories.
Deactivate Webhook.
Permissions:
issues:write: To create labels
Installed Repositories: Install the app into the server repository and client repositories.
Add GitHub App's private keys and ID to Repository Secrets and Variables
- client
- id: client repository's variable
DEMO_CLIENT_APP_ID - private key: client repository's Repository Secret
DEMO_CLIENT_PRIVATE_KEY
- id: client repository's variable
- server
- id: server repository's variable
DEMO_SERVER_APP_ID - private key: server repository's Repository Secret
DEMO_SERVER_PRIVATE_KEY
- id: server repository's variable
Warning
In the getting started, we add private keys to Repository Secrets simply.
But when you use Securefix Action actually, you must manage the Server GitHub App's private key and the server workflow securely.
Only the server workflow must be able to access the server app's private key.
See also How to manage a server GitHub App and a server workflow.
If you change a variable name and a secret name, please fix the workflow.
- If you change a variable name and a secret name, please fix the workflow
- If you change the server repository name, please fix the input
server_repository
- Add
bar.yamlto client repository (Example)
bar.yaml:
names:
- bar- Create a pull request (Example):
Then workflows are run and bar.yaml is fixed automatically:
--- a/bar.yaml
+++ b/bar.yaml
@@ -1,2 +1,2 @@
names:
-- bar
+ - barSecurefix Action composes of four actions:
- csm-actions/securefix-action (action.yaml): Client action
- csm-actions/securefix-action/server/prepare (action.yaml): Server action to prepare for creating commits
- csm-actions/securefix-action/server/commit (action.yaml): Server action to create commits
- csm-actions/securefix-action/server/notify (action.yaml): Server action to notify the server failure
As of Securefix Action v0.2.0, Securefix Action is released using release-js-action. About available versions, please see the document.
- You don't need to pass a GitHub App private key having strong permissions to GitHub Actions workflows on the client side
- You don't need to allow external services to access your code
- You can define custom validation before creating a commit
- Commits are verified (signed)
Client workflows can use a Client GitHub App, but it has only issues:write permission.
Even if the app is abused, the risk is low.
Server action creates a commit to the same repository and branch with the GitHub Actions Artifact.
So it doesn't allow attackers to create a malicious commit to a different repository or a different branch.
You must protect a server GitHub App and a server workflow from attacks securely. There are several ideas:
- GitHub App Private Key:
- Use GitHub Environment Secret
- Restrict the branch
- Use a secret manager such as AWS Secrets Manager and restrict the access by OIDC claims (repository, event, branch, workflow, etc)
- Use GitHub Environment Secret
- Server Workflow
- Restrict members having the write permission of the server repository
- For instance, grant the write permission to only system administrators
- Restrict members having the write permission of the server repository
You can insert custom validation between server/prepare action and server/commit action.
You can use server/prepare action's outputs.
- uses: csm-actions/securefix-action/server/prepare@c5696e3325f3906c5054ad80f3b9cdd92d65173b # v0.1.0
id: prepare
with:
app_id: ${{ vars.DEMO_SERVER_APP_ID }}
app_private_key: ${{ secrets.DEMO_SERVER_PRIVATE_KEY }}
# Custom Validation
- if: fromJson(steps.prepare.outputs.pull_request).user.login != 'suzuki-shunsuke'
run: |
exit 1
- uses: csm-actions/securefix-action/server/commit@c5696e3325f3906c5054ad80f3b9cdd92d65173b # v0.1.0
with:
outputs: ${{ toJson(steps.prepare.outputs) }}
- uses: csm-actions/securefix-action/server/notify@c5696e3325f3906c5054ad80f3b9cdd92d65173b # v0.1.0
failure()
with:
outputs: ${{ toJson(steps.prepare.outputs) }}Securefix Action >= v0.2.0 #123
By default, Securefix Action pushes a commit to the repository and branch where the action is run. But actually there are usecases that you want to push a commit to other repository and branch.
- Scaffold a pull request by
workflow_dispatch - Update GitHub Pages
- Create a pull request to the repository A when the repository B is updated
- etc
Securefix Action can push a commit to the other repository and branch securely. Allowing to push any repository and branch without any restriction is dangerous, so by default changing the repository and branch isn't allowed, meaning the action fails. You can push a commit from only allowed repositories and branches to only allowed repositories and branches.
When pushing a commit to the other repository and branch, you can also create a pull request.
By default, the client workflow name must be securefix for security.
Otherwise, the server/prepare action fails.
You can change the workflow name or remove the restriction using server/prepare action's workflow_name input.
By default, Serverfix Action doesn't allow you to fix workflow files for security.
By default, the server action fails if fixed files include workflow files.
You can allow it by setting server/prepare action's allow_workflow_fix to true.
If you use Server Action in many client repositories and face GitHub API limiting, you can avoid the rate limiting by creating new GitHub Apps and a server repository and splitting clients:
Reference: