This readme describes how to deploy a GitHub Actions Access Token Server.
Important
Be aware that this server is a security sensitive application. It is important to secure the access token server properly and update dependencies regularly. Keep GitHub App credentials as secret as possible.
- Create a GitHub App
Click me
- Create a new GitHub App (User Scope
or Organizations Scope)
- Fill out mandatory fields
- Deactivate Webhook
- Add Mandatory
Repository permissions
- Single file:
Read-only
- Add file path
.github/access-token.yaml
- for repository scoped token policy- Also add file path
.github/access-token.yml
- Also add file path
- Add file path
access-token.yaml
- for owner scoped token policy- Also add file path
access-token.yml
- Also add file path
- Add file path
- Single file:
- Choose permissions you want to allow to request
- Hit
Create GitHub App
button - Take a note of
App ID
- Scroll down to
Private keys
section and clickGenerate a private key
button- private key (
.pem
file) will be downloaded to your machine automatically
- private key (
- Create an Owner Access Token Policy Repository
Important
Ensure that this repository is present before installing the GitHub App Otherwise someone else could create this repo and effectively take over the owner access token policy configuration.
Click me
- Create a new private repository named
.github-access-token
- Ensure only owner admins have access to this repository
- Create owner
access-token.yaml
file at root of the repository with this template content - And adjust the access policy to your liking
- Create owner
- Install GitHub App for Target Repository
Important
By installing the access token GitHub App everybody with write
assess to .github/access-token.yaml
can grant repository access permissions to GitHub Actions workflow runs.
Tip
For organizations on GitHub Enterprise plans it is possible to restrict write
access to .github/access-token.yaml
to repository admins only by using a push ruleset
- Create a new push ruleset
- Set
Ruleset Name
toProtect access token policy
- Set
Enforcement status
toActive
- Hit
Add bypass
, selectRepository admin
and hitAdd selected
- Set
Target repositories
toAll repositories
- Enable
Restrict file paths
- Click
Add file path
, setFile path
to.github/access-token.yaml
and hitAdd file path
- Also add file path
.github/access-token.yml
- Also add file path
- Click
- Hit
Create
button
Click me
- Go to GitHub Apps (User Scope or Organizations Scope)
- Hit
Edit
button of your access token app - Navigate to
Install App
- Hit
Install
button of an account to install your access token app for - Choose
All repositories
orOnly select repositories
- Hit
Install
button
- Create a GitHub Actions Workflow
- see Action README
Click me
-
Build Docker Image
npm run build:docker-container
-
Run Docker Container
docker run --rm -e GITHUB_APP_ID=[YOUR_GITHUB_APP_ID]> \ -e GITHUB_APP_PRIVATE_KEY=$(cat [YOUR_GITHUB_APP.pem]>) \ -p 3000:3000 \ localhost/github-access-token-server
- Optional environment variables
GITHUB_ACTIONS_TOKEN_ALLOWED_SUBJECTS
- A comma separated list of allowed subject patterns e.g.
repo:octocat/*
- If not set or empty all subjects are allowed
- A comma separated list of allowed subject patterns e.g.
- Optional environment variables
-
Adjust actions config
api.url
to docker host
Click me
-
Fork this repository
-
Create a Vercel App for your fork
- Login to your Vercel Account
Add New...
>Project
Import
your forked repository- Edit
Root Directory
toserver/deployments/vercel
- Set environment variables
GITHUB_APP_ID
GITHUB_APP_PRIVATE_KEY
GITHUB_ACTIONS_TOKEN_ALLOWED_SUBJECTS
- A comma separated list of allowed subject patterns e.g.
repo:octocat/*
- If not set or empty all subjects are allowed
- A comma separated list of allowed subject patterns e.g.
- Hit
Deploy
button - Go to project
Settings
>Domains
optional
adjust production domain to your liking
- Take a note of
Production
domain - Set function environment variable
GITHUB_ACTIONS_TOKEN_ALLOWED_AUDIENCE
to vercel projectProduction
domain
-
Adjust actions config
api.url
to vercel projectProduction
domain
Note
This deployment will add extra layer of security by using IAM authenticator in front of the AWS Lambda, therefore the endpoint is secured by AWS identity and access management. All requests to the server are signed with AWS Signature Version 4.
Click me
-
Fork this repository
-
Deploy Cloudformation Stack
- Adjust
GITHUB_ACTIONS_TOKEN_ALLOWED_SUBJECTS
in app-stack.ts to add additional layer of security by defining an ACL of subject patterns.- e.g.
repo:octocat/*
will allow only repositories ofoctocat
owner to request access tokens
- e.g.
-
cd deployments/aws/infrastructure cdk deploy
- Take a note of the cdk outputs
- Login to your AWS account web console
- Edit the
GitHubAppSecret
from cdk output - Set
GITHUB_APP_ID
andGITHUB_APP_PRIVATE_KEY
accordingly to your GitHub App
- Adjust
-
Adjust actions config to cdk outputs as follows
export const config: Config = { api: { url: new URL('[cdk.output.ApiUrl]'), auth: { aws: { roleArn: '[cdk.output.ApiRoleArn]', region: '[cdk.output.ApiRegion]', service: 'lambda', }, }, }, }
Click me
-
Fork this repository
-
TODO
GITHUB_APP_ID=[YOUR_GITHUB_APP_ID] \
GITHUB_APP_PRIVATE_KEY=$(cat [YOUR_GITHUB_APP.pem]) \
GITHUB_ACTIONS_TOKEN_ALLOWED_AUDIENCE=... \
npm start
-
extract policy and permission evaluation to separate lib file
-
review error messages and improve them
- add artificial subjects to error messages
-
ownerAccessPolicy
- statements[].repositories
- variable ${subject.repository} e.g.
repositories: [ "${subject.repo}" ]
- variable ${subject.repository} e.g.
- statements[].repositories
-
Verify repository policy with action run