# GitHub Actions

# Introduction

Currently there are two tokens used in the listed GitHub Actions

GITHUB_TOKEN
RELEASE_TOKEN

# About the `GITHUB_TOKEN` secret

The GITHUB_TOKEN is generated automatically when a workflow job begins, and expires when the job is finished. This token is used to authenticate actions inside the workflows. By default it has read and write access to the repository the worfklow is runnig for. To elevate the permissions to our needs, we use the permissions key inside the respective workflow job. For this reason, it is not necessary to create a special token (PAT) with custom scopes. Further information about GITHUB_TOKEN permissions can be found here.

Example
...
jobs:
  publish-gpr:
    permissions:
      contents: read
      packages: write
...

# About the `RELEASE_TOKEN` secret

The RELEASE_TOKEN is a Personal Access Token (PAT) that is saved as repository secret in the rocket repository settings. A PAT is an authentication token scoped to a single GitHub user account.

To get rid of the this personal connection, it should be considered to use a GitHub App instead.

Why do we even need one in addition to the GITHUB_TOKEN?

The Publish package workflow should start automatically when a release has been successfully published. GitHub prevents workflows from running on events that were caused by another workflow: Triggering a workflow from another workflow

The problem:

GitHub decided that any actions performed by the GitHub Actions bot should not trigger events, which means that you can’t use a workflow to trigger another workflow whilst using the `GITHUB_TOKEN`` secret. This is to prevent circular dependencies that can cause your builds to get stuck in a loop.

This means, that the Create semantic release workflow will not trigger the Publish package workflow. A workaround is to use a PAT environment secret.

# Actions

# Automatic testing

This workflow runs the typescript compiler (build) and unit tests (jest) to make sure the pull request does not introduce errors.

Trigger event	Branches	Token(s)	Token permissions
pull_request	main, develop	auto-generated `GITHUB_TOKEN`	contents: read

# Create semantic release

This workflow runs tests and on success the semantic-release command.

Trigger event	Branches	Token	Token permissions
push	main	auto-generated `GITHUB_TOKEN`	contents: write issues: write pull_requests: write id-token: write
		`RELEASE_TOKEN`	Personal Access Token (classic) with scopes `repo` + `workflow`

# Publish package

The workflow consists of two jobs:

Publishes a rocket package to GitHub Packages when a release was published
Installs the package globally to th runners node environment and runs rocket ignite to test, if the package is executable on [macos-latest, windows-latest, ubuntu-latest].

Event trigger	Token	Token permissions
release[type=published]	auto-generated `GITHUB_TOKEN`	publish-gpr: contents: read packages: write test-package: contents: read packages: read

# Publish beta-/prerelease/feature package

In order to test new features before a release, this workflow enables to publish a "prerelease" or "beta-package", which can then be installed locally. There are two ways to trigger this workflow.

Create a pull request with the respective feature branch and add the label "publish" to the pull request. The workflow will be triggered automatically.
Manually via the Run workflow button in the Actions tab (Publish GitHub Beta Package (Feature) should be selected
- Select the feature branch for which a package is to be created.
- Insert a number in the field Custom number to use as package identifier

To prevent the package name from colliding with the production package, the package is given a name with a customized syntax that looks like this: 1.17.1-dev-60 (assuming that current latest version is 1.17.0).

By default, running yarn publish will tag the package with the "latest" dist-tag. To use another dist-tag, use the --tag flag when publishing.

The version is incremented to a prelease version
The distribution tag "dev-$" gets appended
Adding an additional number allows us to test several features at the same time. The number comes from different sources, depending on which way you went before. If you have added the label "publish" to a pull request, the number of the pull request is used. e.g. https://github.com/kernpunkt/rocket-docs/pull/60 -> The number will be "60"

If you run the workflow manually, you have the option to input a custom number:

The name of the package will be 1.17.1-dev-133

Important: the branch from which the package is to be created must also be selected here.

# Installing the package:

yarn global add @kernpunkt/rocket@1.17.1-dev-133

If you execute yarn global add @kernpunkt/rocket or yarn global add @kernpunkt/rocket@latest you will get the production version.

Trigger event	Branches	Token	Token permissions
pull_request[type=labeled] workflow_dispatch	feature branch	auto-generated `GITHUB_TOKEN`	contents: read packages: write