Availability: BETA
There are several connectors available for GitHub:
- [GitHub Free/Pro/Teams] - for non-Enterprise GitHub organization hosted in github.com.
- [GitHub Enterprise Cloud] - GitHub Enterprise instances hosted by github.com on behalf of your organization.
- [GitHub Enterprise Server] - similar to 'Cloud', but you must customize rules and API host; contact Worklytics for assistance.
The connector uses a GitHub App to authenticate and access the data.
- For Enterprise Server, you must generate a user access token.
- For Cloud, including Free/Pro/Teams/Enterprise, you must provide an installation token for authentication.
- Example Rules
- Example Data : original | sanitized
Both share the same configuration and setup instructions except Administration permission for Audit Log events.
Follow the following steps:
-
Populate
github_organization
variable in Terraform with the name of your GitHub organization. -
From your organization, register a GitHub App with following permissions with Read Only:
- Repository:
- Contents: for reading commits and comments
- Issues: for listing issues, comments, assignees, etc.
- Metadata: for listing repositories and branches
- Pull requests: for listing pull requests, reviews, comments and commits
- Organization
- Administration: (Only for GitHub Enterprise) for listing events from audit log
- Members: for listing teams and their members
- Repository:
NOTES:
- We assume that ALL the repositories are going to be list should be owned by the organization, not the users.
Apart from GitHub instructions please review the following:
- "Homepage URL" can be anything, not required in this flow but required by GitHub.
- Webhooks check can be disabled as this connector is not using them
- Keep
Expire user authorization tokens
enabled, as GitHub documentation recommends
-
Once is created please generate a new
Private Key
. -
It is required to convert the format of the certificate downloaded from PKCS#1 in previous step to PKCS#8. Please run following command:
openssl pkcs8 -topk8 -inform PEM -outform PEM -in {YOUR DOWNLOADED CERTIFICATE FILE} -out gh_pk_pkcs8.pem -nocrypt
NOTES:
- If the certificate is not converted to PKCS#8 connector will NOT work. You might see in logs a
Java error
Invalid PKCS8 data.
if the format is not correct. - Command proposed has been successfully tested on Ubuntu; it may differ for other operating systems.
- Install the application in your organization. Go to your organization settings and then in "Developer Settings". Then, click on "Edit" for your "Github App" and once you are in the app settings, click on "Install App" and click on the "Install" button. Accept the permissions to install it in your whole organization.
- Once installed, the
installationId
is required as it needs to be provided in the proxy as parameter for the connector in your Terraform module. You can go to your organization settings and click onThird Party Access
. Click onConfigure
the application you have installed in previous step and you will find theinstallationId
at the URL of the browser:
https://github.com/organizations/{YOUR ORG}/settings/installations/{INSTALLATION_ID}
Copy the value of installationId
and assign it to the github_installation_id
variable in
Terraform. You will need to redeploy the proxy again if that value was not populated before.
NOTE:
- If
github_installation_id
is not set, authentication URL will not be properly formatted and you will see 401: Unauthorized when trying to get an access token. - If you see 404: Not found in logs please review the IP restriction policies that your organization might have; that could cause connections from psoxy AWS Lambda/GCP Cloud Functions be rejected.
- Update the variables with values obtained in previous step:
PSOXY_GITHUB_CLIENT_ID
withApp ID
value. NOTE: It should beApp Id
value as we are going to use authentication through the App and not client_id.PSOXY_GITHUB_PRIVATE_KEY
with content of thegh_pk_pkcs8.pem
from previous step. You could open the certificate with VS Code or any other editor and copy all the content as-is into this variable.
- Once the certificate has been uploaded, please remove {YOUR DOWNLOADED CERTIFICATE FILE} and
gh_pk_pkcs8.pem
from your computer or store it in a safe place.
We provide a helper script to set up the connector, which will guide you through the steps below and automate some of them. Alternatively, you can follow the steps below directly:
- You have to populate:
github_enterprise_server_host
variable in Terraform with the hostname of your GitHub Enterprise Server (example:github.your-company.com
). This host should be accessible from the proxy instance function, as the connector will need to reach it.github_organization
variable in Terraform with the name of your organization in GitHub Enterprise Server. You can put more than one, just split them in commas (example:org1,org2
).
- From your organization, register a GitHub App
with following permissions with Read Only:
- Repository:
- Contents: for reading commits and comments
- Issues: for listing issues, comments, assignees, etc.
- Metadata: for listing repositories and branches
- Pull requests: for listing pull requests, reviews, comments and commits
- Organization
- Administration: for listing events from audit log
- Members: for listing teams and their members
- Repository:
NOTES:
- We assume that ALL the repositories are going to be listed should be owned by the organization, not the users.
Apart from GitHub instructions please review the following:
- "Homepage URL" can be anything, not required in this flow but required by GitHub.
- "Callback URL" can be anything, but we recommend something like
http://localhost
as we will need it for the redirect as part of the authentication. - Webhooks check can be disabled as this connector is not using them
- Keep
Expire user authorization tokens
enabled, as GitHub documentation recommends
- Once is created please generate a new
Client Secret
. - Copy the
Client ID
and copy in your browser following URL, replacing theCLIENT_ID
with the value you have just copied:
https://your-github-host/login/oauth/authorize?client_id={YOUR CLIENT ID}
- The browser will ask you to accept permissions and then it will redirect you with to the previous
Callback URL
set as part of the application. The URL should look like this:https://localhost/?code=69d0f5bd0d82282b9a11
. - Copy the value of
code
and run the following URL replacing in the placeholders the values ofClient ID
andClient Secret
:
curl --location --request POST 'https://your-github-host/login/oauth/access_token?client_id={YOUR CLIENT ID}&client_secret={YOUR CLIENT SECRET}&code={YOUR CODE}' --header 'Content-Type: application/json' --header 'Accept: application/json'
The response will be something like:
{
"access_token":"ghu_...",
"expires_in":28800,
"refresh_token":"ghr_...",
"refresh_token_expires_in":15724800,
"token_type":"bearer",
"scope":""
}
You will need to copy the value of the refresh_token
.
NOTES:
Code
can be used once, so if you need to repeat the process you will need to generate a new one.
- Update the variables with values obtained in previous step:
psoxy_GITHUB_ENTERPRISE_SERVER_CLIENT_ID
withClient Id
value.psoxy_GITHUB_ENTERPRISE_SERVER_CLIENT_SECRET
withClient Secret
value.psoxy_GITHUB_ENTERPRISE_SERVER_REFRESH_TOKEN
with therefresh_token
.
These instructions have been derived from worklytics-connector-specs; refer to that for definitive information.