GitHub Actions

GitHub Actions is an automation platform built into GitHub that allows you to define and run automated workflows directly in your code repository without relying on any external CI/CD tools.

Common use cases include: automatically running tests after code push, automatically deploying to servers after merging PRs, and running data scraping scripts on a schedule.

GitHub Actions vsPublic repositories are completely free., private repositories have a free quota of 2,000 minutes per month.

Core Concepts

Before writing the configuration file, you need to understand the following core concepts, and the relationships between them are as follows:

仓库（Repository）
└── Workflow（工作流）          ← 一个 .yml 文件 = 一个 Workflow
    ├── Event（触发事件）        ← 什么情况下启动这个 Workflow，如 push、PR
    └── Job（作业）× N          ← 一个 Workflow 可以包含多个并行或串行的 Job
        ├── Runner（运行器）     ← 执行 Job 的服务器，如 ubuntu-latest
        └── Step（步骤）× N     ← Job 内按顺序执行的一系列操作
            ├── Action          ← 可复用的封装好的操作，如 actions/checkout
            └── Run             ← 直接执行 Shell 命令

Create your first Workflow.

1. Directory structure

All Workflow files must be stored in the.github/workflows/directory at the repository root, and the file names must end with.ymlor.yamlThe file name can be customized:

your-repo/
├── .github/
│   └── workflows/
│       ├── ci.yml          ← 持续集成流程（如运行测试）
│       ├── deploy.yml      ← 部署流程
│       └── scheduled.yml   ← 定时任务
├── src/
├── package.json
└── README.md

A repository can have multiple Workflow files, which are independent of each other and are triggered by their respective defined events.

2. The Simplest Workflow

The following is a most basic example: every time code is pushed to the repository, print a line "Hello, GitHub Actions!":

YAML files are very sensitive to indentation, and must usespaceindentation, and cannot use the Tab key. It is recommended to use VS Code and install the YAML plugin, which can detect format errors in real time.

Trigger events (on)

onThe field defines which events trigger this Workflow. It can be a single event or a combination of multiple events.

1. Common Trigger Events

2. Branch or Path Filtering

3. Scheduled Triggers (schedule)

Use a standard Cron expression to define the execution time, with the time zone being UTC (Beijing time = UTC+8, conversion required):

4. Manual trigger (workflow_dispatch)

workflow_dispatchAllows manually clicking a button on the Actions tab of the GitHub web page to start the Workflow, and you can also define input parameters:

Detailed explanation of Jobs and Steps

1. Basic Structure of a Job

2. Runtime environment (runs-on)

GitHub provides the following free hosted runners, which you can choose from as needed:

3. Dependencies between Jobs (needs)

By default, multiple Jobs run in parallel. UseneedsYou can set the execution order of Jobs, forming serial dependency relationships:

4. Conditional Execution (if)

ThroughifYou can control whether a Job or Step executes, commonly used to distinguish branches, determine whether the previous step succeeded, etc.:

Environment Variables and Secrets

1. Environment Variables (env)

Environment variables can be defined at three levels in the Workflow, with the scope decreasing in order:

2. GitHub built-in variables (github context)

GitHub Actions provides a set of built-in context variables, which can be accessed anywhere via${{ }}Syntax reference:

3. Secrets (sensitive information management)

Sensitive information such as passwords, API keys, server addresses, etc.Cannot be written directly in the yml file.(Because the code is public), they must be stored in the Secrets of the GitHub repository.

Setup steps: go to the repository page →Settings → Secrets and variables → Actions→ ClickNew repository secretfill in the name and value, then save.

Introduction to Common Actions

GitHub official and the community provide a large number of ready-to-use Actions, throughuses: action名称@版本references, you can avoid repeatedly writing common operations.

1. actions/checkout (pull code)

Almost the first step of every Workflow is to pull the repository code, using the officialactions/checkout：

2. actions/setup-node (configure Node.js environment)

3. actions/setup-python (Configure Python environment)

4. actions/cache (cache dependencies to accelerate builds)

Downloading dependencies every time the Workflow runs can be slow. Using the cache Action allows dependencies to be cached and directly used on the next run, greatly reducing build time:

5. actions/upload-artifact / download-artifact (transfer files between jobs)

Different Jobs run on independent virtual machines, so files cannot be shared directly. Using artifacts, you can pass one Job's output files to another Job:

Matrix Builds (Matrix)

Matrix builds allow you to run a single Job configuration across multiple environments in parallel, commonly used for compatibility testing across versions and operating systems:

Practical Examples

Example 1: Node.js project CI (automated testing)

Every time code is pushed or a PR is created, automatically install dependencies and run code checks and tests:

Example 2: Python project CI

Example 3: Build and push Docker image(s)

Example 4: Automatically deploy to a server after build

Example 5: Scheduled task (automatically back up database)

Debug技巧

1. Enabling Debug Logs

When a Workflow run fails but the log information is insufficient, you can enable detailed debug mode. Method: go to the repositorySettings → Secrets and variables → Actions, add the following two Secrets (set both values totrue）：

• ACTIONS_RUNNER_DEBUGEnable runner verbose logs
• ACTIONS_STEP_DEBUG: Enable detailed debug logging for each Step.

2. Printing Context Information to Aid Troubleshooting

3. Locally testing Workflow (using act)

Testing the Workflow only by pushing code every time is very inefficient.actis an open-source tool that can simulate running GitHub Actions locally, greatly improving debugging efficiency:

# 安装 act（需要本地已安装 Docker）
# macOS
brew install act

# Linux
curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash

# 在仓库根目录运行所有 Workflow
act

# 只运行指定事件触发的 Workflow
act push

# 只运行指定的 Job
act -j build

When running local tests,actIt uses Docker containers to simulate the GitHub runtime environment, but some Actions (such asactions/cache) may behave differently when simulated locally compared to the real environment. The final results are subject to what actually runs on GitHub.

Common Issues and Notes

1. Permission issue (Permission denied)

If the Workflow needs to push code to the repository or operate on Issues, you need to explicitly declare permissions in the configuration file:

2. Avoiding Workflow loop triggers

If the Workflow automatically pushes code to the repository, it may trigger a new push event, causing an infinite loop. Solution: in the commit message of the automatic commit, add[skip ci]keyword, and GitHub will skip the Workflow trigger for that commit:

git commit -m "自动格式化代码 [skip ci]"

3. YAML Special Character Escaping

InrunIn the Shell command of the field, use${{ }}expression, if the expression contains a colon (:) and other YAML special characters, you need to wrap the entire value in quotes, or instead assign it to an environment variable first and then use it:

For more complete documentation, please refer to the official documentation:https://docs.github.com/zh/actions