Git | Haobin Tan

GitHub Profile

Mon, 21 Mar 2022 00:00:00 +0000

What is GitHub Profile README?

A feature of GitHub
A personalizable introduction section which allows the user to write details about themselves and showcase on his/her GitHub repository
Appears at the top of your GitHub home page (above the pinned repositories)

How to create a GitHub profile README?

Create a new repository and name it with the username of your GitHub account
- After entering the username, GitHub displays a message describing that you’re about to create a GitHub special repository.
Add a README.md in the repository
Write details/interests/skills about yourself in README.md
Set the repository public if it is private during the development

Useful links/tools

GitHub Profile README Generator
Icons: devicon
github-readme-stats
GitHub Readme Streak Stats
Collection of some interesting GitHub Profile README: awesome-github-profile-readme

Reference

How to Create an Impressive GitHub Profile README
Video tutorial:

GitHub Actions

Thu, 05 Jan 2023 00:00:00 +0000

Getting Started

Thu, 05 Jan 2023 00:00:00 +0000

What is GitHub Actions?

GitHub Actions is a continuous integration and continuous delivery (CI/CD) platform that allows you to automate your build, test, and deployment pipeline. You can create workflows that build and test every pull request to your repository, or deploy merged pull requests to production.

GitHub Actions use yaml files to define event, jobs, and steps.

These yaml files are stored in .github/workflows directory.

An event automatically triggers the workflow, which contains a job. The job then uses the steps to control the order, in which the actions are run. These actions are the commands that automate the software testing.

GitHub Actions Components

Source: Getting started with GitHub Actions

You can configure a GitHub Actions workflow to be triggered when an event occurs in your repository, such as a pull request being opened or an issue being created. Your workflow contains one or more jobs which can run in sequential order or in parallel. Each job will run inside its own virtual machine runner, or inside a container, and has one or more steps that either run a script that you define or run an action, which is a reusable extension that can simplify your workflow.

Workflow

A workflow is a configurable automated process that will run one or more jobs.

Defined by YAML files in the .github/workflows directory in a repository. A repository can have multiple workflows, each of which can perform a different set of tasks.
Runs when triggered by an event in your repository, or they can be triggered manually, or at a defined schedule.
You can reference a workflow within another workflow, see “Reusing workflows.”

(For more information about workflows, see “Using workflows.”)

Events

An event is a specific activity in a repository that triggers a workflow run.

For example, activity can originate from GitHub when someone creates a pull request, opens an issue, or pushes a commit to a repository.

For a complete list of events that can be used to trigger workflows, see Events that trigger workflows.

Jobs

A job is a set of steps in a workflow that execute on the same runner.

Each step is either a shell script that will be executed, or an action that will be run.
Steps are executed in order and are dependent on each other.
Each step is executed on the same runner. (you can share data from one step to another. )

By default, jobs have no dependencies and run in parallel with each other.

When a job takes a dependency on another job, it will wait for the dependent job to complete before it can run.

Actions

An action is a custom application for the GitHub Actions platform that performs a complex but frequently repeated task.
Use an action to help reduce the amount of repetitive code that you write in your workflow files.
You can write your own actions (see “Creating actions”), or you can find actions to use in your workflows in the GitHub Marketplace.

Runners

A runner is a server that runs your workflows when they’re triggered.

A runner is a server that runs your workflows when they’re triggered.
GitHub provides Ubuntu Linux, Microsoft Windows, and macOS runners to run your workflows. Each workflow run executes in a fresh, newly-provisioned virtual machine.

Understanding the Workflow File

Let’s say we have created a learn-github-actions.yml in the .github/workflows/ directory in the repository:

# Optional
# The name of the workflow 
# as it will appear in the "Actions" tab of the GitHub repository. 
name: learn-github-actions

# Optional
# The name for workflow runs generated from the workflow, 
# which will appear in the list of workflow runs on your repository's "Actions" tab.
run-name: ${{ github.actor }} is learning GitHub Actions

# Trigger for this workflow.
# Here we use the `push` event, so a workflow run is triggered every time
# someone pushes a change to the repository or merges a pull request.
on: [push]

jobs: # Group together all the jobs that run in this workflow
 check-bats-version: # Define a job named `check-bats-version`
 runs-on: ubuntu-latest # specify the runner on which this job runs
 steps: # Group together all the steps that run in this job
 # The `uses` keyword specifies that this step will run `v3` of the `actions/checkout` action. 
 # This is an action that checks out your repository onto the runner,`
 # allowing you to run scripts or other actions against your code.
 # You should use the checkout action any time your workflow will run against the repository's code.
 - uses: actions/checkout@v3
 - uses: actions/setup-node@v3
 with:
 node-version: '14'

 # The `run` keyword tells the job to execute a command on the runner.
 - run: npm install -g bats
 - run: bats -v

Visualize the workflow we created in a hierarchy:

As we can see, each step executes a single action or shell script. Steps 1 and 2 run actions, while steps 3 and 4 run shell scripts.

View the Activity for a Workflow Run

When your workflow is triggered, a workflow run is created that executes the workflow. After a workflow run has started, you can see a visualization graph of the run’s progress and view each step’s activity on GitHub.

A step by step guide see: Viewing the activity for a workflow run

Quick Start Demo

See Quickstart for GitHub Actions

Reference

Actions Usage

Thu, 05 Jan 2023 00:00:00 +0000

Overview

Actions are the building blocks that power your workflow.

A workflow can contain actions created by the community or customized directly within your repository.

Adding an Action to Workflow

Adding an action from GitHub Marketplace

You can find a number of useful actions in GitHub Marketplace.

An action’s listing page includes the action’s version and the workflow syntax required to use the action. To keep your workflow stable even when updates are made to an action, you can reference the version of the action to use by specifying the Git or Docker tag number in your workflow file.

Steps:

Navigate to the action you want to use in your workflow.
Choose the version you want to use and copy the workflow syntax
Paste the syntax as a new step in your workflow. (For more information, see “Workflow syntax for GitHub Actions.”)
If the action requires you to provide inputs, set them in your workflow. (For information on inputs an action might require, see “Using inputs and outputs with an action.”)

Adding an action from the same repository

If an action is defined in the same repository where your workflow file uses the action, you can reference the action with either the ‌{owner}/{repo}@{ref} or ./path/to/dir syntax in your workflow file.

Example:

Repository file structure:

|-- hello-world (repository)
| |__ .github
| └── workflows
| └── my-first-workflow.yml
| └── actions
| |__ hello-world-action
| └── action.yml

Workflow file:

jobs:
 build:
 runs-on: ubuntu-latest
 steps:
 # This step checks out a copy of your repository.
 - uses: actions/checkout@v3
 # This step references the directory that contains the action.
 - uses: ./.github/actions/hello-world-action

Adding an action from a different repository

If an action is defined in a different repository than your workflow file, you can reference the action with the {owner}/{repo}@{ref} syntax in your workflow file. The action must be stored in a public repository.

Example:

jobs:
 my_first_job:
 steps:
 - name: My first step
 uses: actions/setup-node@v3

Referencing a container on Docker Hub

If an action is defined in a published Docker container image on Docker Hub, you must reference the action with the docker://{image}:{tag} syntax in your workflow file.

To protect your code and data, it is strongly recommend you verify the integrity of the Docker container image from Docker Hub before using it in your workflow.

Example:

jobs:
 my_first_job:
 steps:
 - name: My first step
 uses: docker://alpine:3.8

Using Release Management for Your Custom Actions

Similar to any dependency, you should indicate the version of the action you’d like to use based on your comfort with automatically accepting updates to the action.

You will designate the version of the action in your workflow file. Check the action’s documentation for information on their approach to release management, and to see which tag, branch, or SHA value to use.

Using tags

Tags are useful for letting you decide when to switch between major and minor versions, but these are more ephemeral and can be moved or deleted by the maintainer.

Example:

steps:
 - uses: actions/javascript-action@v1.0.1

Using SHAs

If you need more reliable versioning, you should use the SHA value associated with the version of the action, as SHAs are immutable and therefore more reliable than tags or branches.
However this approach means you will not automatically receive updates for an action, including important bug fixes and security updates.
You must use a commit’s full SHA value, and not an abbreviated value. This example targets an action’s SHA.

Example:

steps:
 - uses: actions/javascript-action@172239021f7ba04fe7327647b213799853a9eb89

Using branches

Specifying a target branch for the action means it will always run the version currently on that branch. However, this approach can create problems if an update to the branch includes breaking changes.

Example:

steps:
 - uses: actions/javascript-action@main # targets a branch name `main`

Using Inputs and Outputs with an Action

An action often accepts or requires inputs and generates outputs that you can use.
- E.g., an action might require you to specify a path to a file, the name of a label, or other data it will use as part of the action processing.
To see the inputs and outputs of an action, check the action.yml or action.yaml in the root directory of the repository.

Example:

name: "Example"
description: "Receives file and generates output"
inputs:
 file-path: # id of input
 description: "Path to test script"
 required: true
 default: "test-file.js"
outputs:
 results-file: # id of output
 description: "Path to results file"

The inputs keyword defines a required input called file-path, and includes a default value that will be used if none is specified.
The outputs keyword defines an output called results-file, which tells you where to locate the results.

Reference

Finding and customizing actions

Customization Techniques

Fri, 06 Jan 2023 00:00:00 +0000

GitHub Actions allow you to customize your workflows to meet the unique needs of your application and team.

Using Variables in Workflow

GitHub Actions include default environment variables for each workflow run. If you need to use custom environment variables, you can set these in your YAML workflow file.

Example:

jobs:
 example-job:
 steps:
 - name: Connect to PostgreSQL
 run: node client.js
 env:
 POSTGRES_HOST: postgres
 POSTGRES_PORT: 5432

In this example, we create custom variables named POSTGRES_HOST and POSTGRES_PORT. These variables are then available to the node client.js script.

Add Scripts to Workflow

You can use actions to run scripts and shell commands, which are then executed on the assigned runner.

Example: use the run keyword to execute npm install -g bats on the runner.

jobs:
 example-job:
 steps:
 - run: npm install -g bats

To run a script as an action, you can store the script in your repository and supply the path and shell type. Example:

jobs:
 example-job:
 steps:
 - name: Run build script
 run: ./.github/scripts/build.sh
 shell: bash

If your job generates files that you want to share with another job in the same workflow, or if you want to save the files for later reference, you can store them in GitHub as artifacts.

Artifacts are the files created when you build and test your code.

Might include binary or package files, test results, screenshots, or log files.
Are associated with the workflow run where they were created and can be used by another job.

All actions and workflows called within a run have write access to that run’s artifacts.

Example: create a file and then upload it as an artifact

jobs:
 example-job:
 name: Save output
 steps:
 - shell: bash
 run: | expr 1 + 1 > output.log
 - name: Upload output file
 uses: actions/upload-artifact@v3
 with:
 name: output-log-file
 path: output.log

To download an artifact from a separate workflow run, you can use the actions/download-artifact action. To download an artifact from the same workflow run, your download job should specify needs: upload-job-name so it doesn’t start until the upload job finishes.

Example: download the artifact named output-log-file.

jobs:
 example-job:
 steps:
 - name: Download a single artifact
 uses: actions/download-artifact@v3
 with:
 name: output-log-file

Reference

Essential features of GitHub Actions

Expressions

Fri, 06 Jan 2023 00:00:00 +0000

Overview

You can use expressions to programmatically set environment variables in workflow files and access contexts. An expression can be any combination of literal values, references to a context, or functions. You can combine literals, context references, and functions using operators.

Expressions are commonly used with the conditional if keyword in a workflow file to determine whether a step should run. When an if conditional is true, the step will run.

You need to use specific syntax

${{ <expression> }}

to tell GitHub to evaluate an expression rather than treat it as a string.

When you use expressions in an if conditional, you may omit the expression syntax (${{ }}) because GitHub automatically evaluates the if conditional as an expression.

Example expression in an `if` conditional

steps:
 - uses: actions/hello-world-javascript-action@v1.1
 if: ${{ <expression> }}

Example setting an environment variable

env:
 MY_ENV_VAR: ${{ <expression> }}

Literals

You can use boolean, null, number, or string data types.

Data type	Literal value
`boolean`	`true` or `false`
`null`	`null`
`number`	Any number format supported by JSON.
`string`	You don’t need to enclose strings in `${{` and `}}`. However, if you do, you must use single quotes (`'`) around the string. To use a literal single quote, escape the literal single quote using an additional single quote (`''`). Wrapping with double quotes (`"`) will throw an error.

Example:

env:
 myNull: ${{ null }}
 myBoolean: ${{ false }}
 myIntegerNumber: ${{ 711 }}
 myFloatNumber: ${{ -9.2 }}
 myHexNumber: ${{ 0xff }}
 myExponentialNumber: ${{ -2.99e-2 }}
 myString: Mona the Octocat
 myStringInBraces: ${{ 'It''s open source!' }}

Operators

Operator	Description
`( )`	Logical grouping
`[ ]`	Index
`.`	Property de-reference
`!`	Not
`<`	Less than
`<=`	Less than or equal
`>`	Greater than
`>=`	Greater than or equal
`==`	Equal
`!=`	Not equal
`&&`	And
`

GitHub performs loose equality comparisons.

If the types do not match, GitHub coerces the type to a number. GitHub casts data types to a number using these conversions:

Type Result

Null 0

Boolean true returns 1 false returns 0

String Parsed from any legal JSON number format, otherwise NaN. Note: empty string returns 0.

Array NaN

Object NaN
A comparison of one NaN to another NaN does not result in true.
GitHub ignores case when comparing strings.
Objects and arrays are only considered equal when they are the same instance.

Type	Result
Null	`0`
Boolean	`true` returns `1` `false` returns `0`
String	Parsed from any legal JSON number format, otherwise `NaN`. Note: empty string returns `0`.
Array	`NaN`
Object	`NaN`

Functions

GitHub offers a set of built-in functions that you can use in expressions.

Some functions cast values to a string to perform comparisons. GitHub casts data types to a string using these conversions:

Type	Result
Null	`''`
Boolean	`'true'` or `'false'`
Number	Decimal format, exponential for large numbers
Array	Arrays are not converted to a string
Object	Objects are not converted to a string

conatins

contains( search, item )

Returns true if search contains item.
If search is an array, this function returns true if the item is an element in the array.
If search is a string, this function returns true if the item is a substring of search. This function is not case sensitive. Casts values to a string.

Example

contains('Hello world', 'llo') returns true.

startsWith

startsWith( searchString, searchValue )

Returns true when searchString starts with searchValue. This function is not case sensitive. Casts values to a string.

Example

startsWith('Hello world', 'He') returns true.

endsWith

endsWith( searchString, searchValue )

Returns true if searchString ends with searchValue. This function is not case sensitive. Casts values to a string.

Example

endsWith('Hello world', 'ld') returns true.

format

format( string, replaceValue0, replaceValue1, ..., replaceValueN)

Replaces values in the string, with the variable replaceValueN.
Variables in the string are specified using the {N} syntax, where N is an integer. You must specify at least one replaceValue and string. There is no maximum for the number of variables (replaceValueN) you can use.
Escape curly braces using double braces.

Example

format('{{Hello {0} {1} {2}!}}', 'Mona', 'the', 'Octocat') returns ‘{Hello Mona the Octocat!}’.

join

join( array, optionalSeparator )

The value for array can be an array or a string.
All values in array are concatenated into a string.
- If you provide optionalSeparator, it is inserted between the concatenated values. Otherwise, the default separator , is used. Casts values to a string.

toJSON

toJSON(value)

Returns a pretty-print JSON representation of value.
You can use this function to debug the information provided in contexts.

fromJSON

fromJSON(value)

Returns a JSON object or JSON data type for value.
You can use this function to provide a JSON object as an evaluated expression or to convert environment variables from a string.

hashFiles

hashFiles(path)

Returns a single hash for the set of files that matches the path pattern.
- You can provide a single path pattern or multiple path patterns separated by commas.
- The path is relative to the GITHUB_WORKSPACE directory and can only include files inside of the GITHUB_WORKSPACE.
This function calculates an individual SHA-256 hash for each matched file, and then uses those hashes to calculate a final SHA-256 hash for the set of files.
- If the path pattern does not match any files, this returns an empty string.

Status Check Functions

You can use the following status check functions as expressions in if conditionals. A default status check of success() is applied unless you include one of these functions.

success

Returns true when none of the previous steps have failed or been canceled.

Example

steps:
 ...
 - name: The job has succeeded
 if: ${{ success() }}

always

Causes the step to always execute, and returns true, even when canceled. A job or step will not run when a critical failure prevents the task from running. For example, if getting sources failed.

Example

if: ${{ always() }}

cancelled

Returns true if the workflow was canceled.

Example

if: ${{ cancelled() }}

failure

Returns true when any previous step of a job fails. If you have a chain of dependent jobs, failure() returns true if any ancestor job fails.

Example

steps:
 ...
 - name: The job has failed
 if: ${{ failure() }}

ailure with conditions

You can include extra conditions for a step to run after a failure, but you must still include failure() to override the default status check of success() that is automatically applied to if conditions that don’t contain a status check function.

Example

steps:
 ...
 - name: Failing step
 id: demo
 run: exit 1
 - name: The demo step has failed
 if: ${{ failure() && steps.demo.conclusion == 'failure' }}

Object filters

You can use the * syntax to apply a filter and select matching items in a collection.

E.g., let’s say we have an array of objects named fruits:

[
 { "name": "apple", "quantity": 1 },
 { "name": "orange", "quantity": 2 },
 { "name": "pear", "quantity": 1 }
]

The filter fruits.*.name returns the array [ "apple", "orange", "pear" ].

You may also use the * syntax on an object. For example, suppose you have an object named vegetables:

{
 "scallions":
 {
 "colors": ["green", "white", "red"],
 "ediblePortions": ["roots", "stalks"],
 },
 "beets":
 {
 "colors": ["purple", "red", "gold", "white", "pink"],
 "ediblePortions": ["roots", "stems", "leaves"],
 },
 "artichokes":
 {
 "colors": ["green", "purple", "red", "black"],
 "ediblePortions": ["hearts", "stems", "leaves"],
 },
}

The filter vegetables.*.ediblePortions could evaluate to:

[
 ["roots", "stalks"],
 ["hearts", "stems", "leaves"],
 ["roots", "stems", "leaves"],
]

Since objects don’t preserve order, the order of the output can not be guaranteed.

Reference

Expressions

Git

Mon, 21 Mar 2022 00:00:00 +0000

Git | Haobin Tan

GitHub Profile

What is GitHub Profile README?

How to create a GitHub profile README?

Useful links/tools

Reference

GitHub Actions

Getting Started

What is GitHub Actions?

GitHub Actions Components

Workflow

Events

Jobs

Actions

Runners

Understanding the Workflow File

View the Activity for a Workflow Run

Quick Start Demo

Reference

Actions Usage

Overview

Adding an Action to Workflow

Adding an action from GitHub Marketplace

Adding an action from the same repository

Adding an action from a different repository

Referencing a container on Docker Hub

Using Release Management for Your Custom Actions

Using tags

Using SHAs

Using branches

Using Inputs and Outputs with an Action

Reference

Customization Techniques

Using Variables in Workflow

Add Scripts to Workflow

Sharing Data between Jobs

Reference

Expressions

Overview

Example expression in an if conditional

Example setting an environment variable

Literals

Operators

Functions

conatins

Example

startsWith

Example

endsWith

Example

format

Example

join

toJSON

fromJSON

hashFiles

Status Check Functions

success

Example

always

Example

cancelled

Example

failure

Example

ailure with conditions

Example

Object filters

Reference

Git

Example expression in an `if` conditional