Trigger another GitHub Workflow — without using a Personal Access Token

📚 As of September 8, 2022, GitHub introduced exemptions that permit workflow_dispatch and repository_dispatch events to trigger workflows. The steps described in this post are no longer necessary in those cases.

GitHub executes each Workflow with a token — ${{ github.token }} — that has permissions to push commits back to a repository; however, to prevent infinite Workflow loops, the tasks performed with this token do not trigger further Workflow runs.

When you use the repository’s GITHUB_TOKEN to perform tasks on behalf of the GitHub Actions app, events triggered by the GITHUB_TOKEN will not create a new workflow run⌝

GitHub recommends a Personal Access Token for workflows that need the ability to trigger further workflows. Unfortunately, Personal Access Tokens cannot be scoped to a repository, violating the principle of least privilege. Fortunately, there is an alternative: a Deploy Key.

Deploy Keys

A deploy key⌝ is an SSH key that is stored on your server and grants access to a single GitHub repository. This key is attached directly to the repository instead of to a personal user account.

A Deploy Key does not have any GitHub imposed restrictions; for GitHub Actions, it is treated like any other user: any authenticated Git operation will trigger GitHub Workflows.

Adding a Deploy Key is a simple 3 step process.

1. Generate a new OpenSSH Key
2. Add Deploy Key to GitHub Repository
3. Authenticate Git Operations With Deploy Key

1. Generate a new OpenSSH Key

An Ed25519 key should be generated for each repository; a key should not be used for more than one repository.

🤖 Don’t have access to a terminal? Run this code online using Replit⌝ to generate an example key.

2. Add Deploy Key to GitHub Repository

1. Create a new Secret via Settings > Secrets > New repository secret with the name COMMIT_KEY and your Ed25519 private key as the value
2. Add the public key to the GitHub Repository via Settings > Deploy keys > Add deploy key with Allow write access selected

Settings > Secrets > New repository secret

Settings > Deploy keys > Add deploy key

3. Authenticate Git Operations With Deploy Key

Pass the deploy key secret with ssh-key to actions/checkout to authenticate Git operations using the Deploy Key.

You’re now ready to use GitHub Actions to build Workflows that form part of a complex pipeline. A forkable demo is available on GitHub, in pr-mpt/examples-workflow-trigger.

📝 Keep in mind; secrets are not accessible in unprivileged workflows — therefore, Workflow runs triggered in Pull Requests by outside contributors will not have access to the secret.