Many AL-Go for GitHub workflows will require a GhTokenWorkflow secret. The GhTokenWorkflow secret should contain either a Personal Access Token with a specific set of permissions or it should be a compressed JSON containing the GitHub App Client Id and a Private Key of an installed GitHub app, with the same permissions.
The Personal Access Token comes in two flavors as well: Classic or Fine-grained.
Note
The permissions assigned to the GitHub App or PAT specified in the GhTokenWorkflow secret should not be confused with the repositories for which the GhTokenWorkflow secret is made available. If the secret is available to a repository, for which the GitHub App or PAT haven't been given permissions, it will not work.
Note
You can define the GhTokenWorkflow under an environment and set the updateALGoSystemFilesEnvironment to the environment name, in order to enable an approval workflow or set permissions on who is allowed to use the secret for Update AL-Go System Files.
The most secure way of specifying the GhTokenWorkflow is to use a GitHub App. The GitHub App doesn't contain any code, it is just a specification of what indirect permissions are given to the workflows holding the Client Id and a Private Key. When creating a GitHub App, you also specify whether the app is intended for your organization only or it can be installed in other organizations, and during installation you specify which repositories the GitHub App should be installed in. For GitHub Apps, the Client Id and Private Key only works with repositories where the GitHub App is installed.
The GitHub App Client Id and the Private Key are used to generate a JWT token, which is used to request a short lived (one hour) access token. This access token is used when doing API requests and more, the private key is never sent over the network and will remain a secret in your repository. If the Private Key is compromised, you will need to create a new Private Key and delete the compromised key in order to stop evil people from having access.
Note
When using a GitHub App for authentication all Commits and Pull Requests generated by workflows authenticated with this GitHub App will show as opened by the GitHub App tagged bot.
To create a GitHub App for authentication, navigate to Register new GitHub App in a browser to create a GitHub app owned by the creator or navigate to https://github.com/organizations/<organization name>/settings/apps/new if you want to create a GitHub app owned by an organization. Name it, give it a description and set the homepage URL to the AL-Go repo (or whatever you like).
This GitHub App is not going to be used to authenticate users, nor does it have any post installation url or webhooks - these fields can be left blank. Scroll down to permissions and assign Read and Write permissions to Contents, Pull Requests and Workflows. You also need to assign Read-only permissions to Actions.
The GitHub App doesn't need any organizational, account or enterprise permissions. Now just specify whether this app can be installed in any organization or only in the organization in which is was created. Note that the Client Id and Private Key (which we create in a moment) will give access to all repositories in which the app is installed (in all organizations).
After creating the GitHub App, GitHub will display the Client ID of the GitHub App. Copy the value of the Client ID to the clipboard. GitHub also suggests to create a Private Key in order to install the App.
After creating the private key, the key is automatically downloaded to your machine.
Now, navigate to Install App and install the App in the organization and repositories in which it's needed
Now, with the newly downloaded Private Key available, you now need to run the following PowerShell snippet to create the value, which you need to specify in the GhTokenWorkflow secret:
$githubAppClientId = '<GitHub App Client ID for your app>'
$privateKeyFile = '<full path of the downloaded private key file>'
@{"GitHubAppClientId"=$githubAppClientId; "PrivateKey" = ([string]::Join('',[System.IO.File]::ReadAllLines($privateKeyFile))) } | ConvertTo-Json -Compress -Depth 99 | Set-ClipboardOn github.com, open Settings in your repository or organization and select Secrets. Choose the New repository or organizational secret button and create a secret called GHTOKENWORKFLOW and paste the GitHub App Auth value into the value field and choose Add secret.
Personal Access Tokens are less secure and are impersonating the creator of the token. All Commits and Pull Requests generated by workflows authenticated with this PAT will show as opened by the creator of the PAT. Personal Access Tokens cannot have permissions to anything the creator doesn't have permissions to.
Personal Access Tokens are sent over the network with every API call in GitHub and can (if compromised) be misused by evil people during the validity time of the token. If you decide to use Personal Access Tokens, we recommend giving them a short expiration date and recycle them frequently.
The Fine-grained Personal Access Token is limited in scope to an organization and a number of repositories inside that organization. If compromised, this token can be used everywhere to access the repositories with the permissions given to the token, impersonating the creator of the token.
The Classic Personal Access Token is the least secure option. The Classic Personal Access Token is not limited in scope to an organization or a set of repositories, instead the token can be used everywhere to access the repositories with the permissions given to the token on all organizations and all repositories, impersonating the creator of the token.
To create a fine-grained personal access token for authentication, navigate to New fine-grained personal access token in a browser. Name it, set the expiration date, select the resource owner (this needs to be the organization or user who is the owner of the repositories in which the token is used) and specify which repositories to include.
You need and assign Read and Write permissions to Contents, Pull Requests and Workflows. You also need to assign Read-only permissions to Actions. After generating the token, the value will be shown. Remember to copy the value to the Clipboard and use this as the value for the GhTokenWorkflow secret. Inspecting the token after creation could look like this:
On github.com, open Settings in your repository or organization and select Secrets. Choose the New repository or organizational secret button and create a secret called GHTOKENWORKFLOW and paste the GitHub App Auth value into the value field and choose Add secret.
To create a classic personal access token for authentication, navigate to New personal access token (classic) in a browser. Name it, set the expiration date and check the workflow option in the list of scopes.
After generating the token, the value will be shown. Remember to copy the value to the Clipboard and use this as the value for the GhTokenWorkflow secret.
On github.com, open Settings in your repository or organization and select Secrets. Choose the New repository or organizational secret button and create a secret called GHTOKENWORKFLOW and paste the GitHub App Auth value into the value field and choose Add secret.
