GHA

1. Workflow
2. Runner
3. Variables
4. Persist Output
5. Tokens and Secrets

Workflow

Workflows are YMAL files located under the .github/workflows directory of your GitHub repo.

A workflow has one or more jobs. Each job has one or more steps that execute on a runner. Each step is a user-defined Shell script or well-known actions like actions/checkout. Workflows can be triggered by one or more events.

Here is an quick illustration of core concepts.

Check workflow examples at https://github.com/outsinre/kong/tree/master/.github/workflows.

Please refer to Understanding GitHub Actions.

Runner

Each GitHub-hosted runner is a new virtual machine (VM) hosted by GitHub with the runner application and other tools preinstalled, and is available with Ubuntu Linux, Windows, or macOS operating systems. When you use a GitHub-hosted runner, machine maintenance and upgrades are taken care of for you.

Each workflow job has its own standalone runner and specifies the types of runners by runs-on.

See more details about runner at Using GitHub-hosted runners.

Variables

Variables can be categorized into 2 types:

1. Default variables.

   1. Default environment (Shell) variables.

            
      ${{ env.GITHUB_REPOSITORY }}
            
      $GITHUB_REPOSITORY
            
      

   2. Default context variables.

            
      ${{ github.repository }}
            
      

2. Custom variables.

   1. Custom environment (Shell) variables defined via the env key.

      env:
        my_var: foo
      

   2. Custom configuration variables defined at the "Settings" of organization, repository, or environment level.

To access variables, we use context in the form as follows. Most commonly used contexts are github and env.

${{ context.property }}

# example
${{ env.GITHUB_REPOSITORY }}

Specially, the env context has the following two forms:

1. Workflow syntax as mentioned above.
2. Shell syntax, like $GITHUB_REPOSITORY. This form is usually used within the run key.

The difference between the two forms is that the workflow syntax is interpolated before the workflow jobs are sent to a runner, while the Shell syntax is interpolated at runtime.

Persist Output

We can share values among steps of a job, or even among jobs.

1. To share values among steps of a job, please use GITHUB_ENV.

   GITHUB_ENV is an environment variable storing the pathname of a environment file on the runner. We can access it via Shell syntax in run steps and workflow syntax in non-Shell context. See Using the env context to access environment variable values.

      
   # define in a step
   echo "MY_VAR=myValue" >> $GITHUB_ENV
   
   # reference in another step
   ${MY_VAR}
   # -or-
   ${{ env.MY_VAR }}
      
   

   However, in the well-know actions/github-script, we access the environment variables via process.env.my_var.

2. To share values among jobs, please try the following methods.

   1. Use environment variable GITHUB_OUTPUT to declare the output of a job. Similar to GITHUB_ENV above, but it can only be accessed with workflow syntax.

            
      # define output1 in a job
      run: echo "my_var=hello" >> "$GITHUB_OUTPUT"
      output1: ${{ steps.<step-id>.outputs.my_var }}
      
      # reference output1 in another job
      ${{needs.<job_id>.outputs.output1}}
            
      

      Of course, GITHUB_OUTPUT can also be used to share values among steps of a job.

            
      # reference output1 in another step within the same job
      ${{ steps.<step-id>.outputs.output1_var }}
            
      

   2. Storing workflow data as artifacts.

Tokens and Secrets

1. GitHub tokens, namely Personal Access Tokens, are opaque strings (credentials) defined for your GitHub account at https://github.com/settings/tokens.

2. GitHub secrets are names declared at the "Settings" of organization, repository, or repository environment level. Any values (e.g. JSON string) can be assigned to secrets. But to operate the repo, we assign tokens to secrets.

   Once set, secrets are available to workflows via $.

   There is a special secret $ which is automatically issued by GitHub when a workflow is triggered, and you don not need to create this explicitly. It is different from the personal access tokens. Refer to Automatic token authentication .

Refer to Using secrets in GitHub Actions.