# GitHub Actions


# Introduction

Currently there are two tokens used in the listed GitHub Actions


# 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.

      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.

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

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:

  1. Publishes a rocket package to GitHub Packages when a release was published
  2. 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

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.

  1. Create a pull request with the respective feature branch and add the label "publish" to the pull request. The workflow will be triggered automatically.
  2. 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.

  1. The version is incremented to a prelease version
  2. The distribution tag "dev-$" gets appended
  3. 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
feature branch auto-generated GITHUB_TOKEN contents: read
packages: write