GitHub Actions

https://docs.github.com/en/actions
Admin
GitHub Actions automates, customizes, and executes software development workflows directly in your...
Tokens:455,283
Snippets:3,284
Trust Score:10
Update:3 days ago
Show doc for...
Tokens:
Raw
### Example: Stopping and starting workflow commands (Windows)

Source: https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-commands?tool=bash

This workflow demonstrates stopping and starting workflow commands on Windows. It uses `New-Guid` to generate a unique token, stops commands, logs a warning that is not processed, then resumes commands and logs another warning that is processed.

```yaml
jobs:
  workflow-command-job:
    runs-on: windows-latest
    steps:
      - name: Disable workflow commands
        run: |
          Write-Output '::warning:: This is a warning message, to demonstrate that commands are being processed.'
          $stopMarker = New-Guid
          Write-Output "::stop-commands::$stopMarker"
          Write-Output '::warning:: This will NOT be rendered as a warning, because stop-commands has been invoked.'
          Write-Output "::$stopMarker::"
          Write-Output '::warning:: This is a warning again, because stop-commands has been turned off.'

```

--------------------------------

### Example: Stopping and starting workflow commands (Ubuntu)

Source: https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-commands?tool=bash

This workflow demonstrates stopping and starting workflow commands on Ubuntu. It uses `uuidgen` to generate a unique token, stops commands, logs a warning that is not processed, then resumes commands and logs another warning that is processed.

```yaml
jobs:
  workflow-command-job:
    runs-on: ubuntu-latest
    steps:
      - name: Disable workflow commands
        run: |
          echo '::warning:: This is a warning message, to demonstrate that commands are being processed.'
          stopMarker=$(uuidgen)
          echo "::stop-commands::$stopMarker"
          echo '::warning:: This will NOT be rendered as a warning, because stop-commands has been invoked.'
          echo "::$stopMarker::"
          echo '::warning:: This is a warning again, because stop-commands has been turned off.'

```

--------------------------------

### Example setting an environment variable

Source: https://docs.github.com/en/actions/concepts/workflows-and-actions/expressions

Example setting an environment variable

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

--------------------------------

### Example: Running a step in the background

Source: https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions

Starts a server in the background, runs tests, then waits for the server step to finish. Use `background: true` for long-running processes and `wait` to synchronize.

```yaml
steps:
  - name: Start server
    id: server
    run: npm start
    background: true

  - name: Run tests against the server
    run: npm test

  - name: Wait for the server step to finish
    wait: server

```

--------------------------------

### Install dependencies with Bundler and setup-ruby

Source: https://docs.github.com/en/actions/tutorials/build-and-test-code/ruby

Uses the ruby/setup-ruby action to set up Ruby 3.1 and automatically determine and install the appropriate Bundler version before running bundle install.

```yaml
# This workflow uses actions that are not certified by GitHub.
# They are provided by a third-party and are governed by
# separate terms of service, privacy policy, and support
# documentation.
steps:
- uses: actions/checkout@v6
- uses: ruby/setup-ruby@ec02537da5712d66d4d50a0f33b7eb52773b5ed1
  with:
    ruby-version: '3.1'
- run: bundle install
```

--------------------------------

### Example: Adding configurations with matrix include

Source: https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions

This matrix runs 10 jobs, one for each combination of `os` and `version`, plus a job for `windows-latest` and version 17.

```yaml
jobs:
  example_matrix:
    strategy:
      matrix:
        os: [macos-latest, windows-latest, ubuntu-latest]
        version: [12, 14, 16]
        include:
          - os: windows-latest
            version: 17
```

--------------------------------

### Install Go dependencies using go get

Source: https://docs.github.com/en/actions/tutorials/build-and-test-code/go

Run `go get` commands within a workflow step to fetch dependencies for the current project or specific external module versions.

```yaml
    steps:
      - uses: actions/checkout@v6
      - name: Setup Go
        uses: actions/setup-go@v5
        with:
          go-version: '1.21.x'
      - name: Install dependencies
        run: |
          go get .
          go get example.com/octo-examplemodule
          go get example.com/octo-examplemodule@v1.3.4
```

--------------------------------

### Install and upgrade pip, setuptools, and wheel

Source: https://docs.github.com/en/actions/tutorials/build-and-test-code/python

Sets up Python 3.x with actions/setup-python and upgrades pip, setuptools, and wheel on the runner before running builds or tests.

```yaml
steps:
- uses: actions/checkout@v6
- name: Set up Python
  uses: actions/setup-python@v5
  with:
    python-version: '3.x'
- name: Install dependencies
  run: python -m pip install --upgrade pip setuptools wheel
```

--------------------------------

### Example journalctl output for a self-hosted runner

Source: https://docs.github.com/en/actions/how-tos/manage-runners/self-hosted-runners/monitor-and-troubleshoot?platform=linux

This is an example of the log output when monitoring the runner service. It shows the runner starting, connecting to GitHub, listening for jobs, and completing a job named testAction.

```text
Feb 11 14:57:07 runner01 runsvc.sh[962]: Starting Runner listener with startup type: service
Feb 11 14:57:07 runner01 runsvc.sh[962]: Started listener process
Feb 11 14:57:07 runner01 runsvc.sh[962]: Started running service
Feb 11 14:57:16 runner01 runsvc.sh[962]: √ Connected to GitHub
Feb 11 14:57:17 runner01 runsvc.sh[962]: 2020-02-11 14:57:17Z: Listening for Jobs
Feb 11 16:06:54 runner01 runsvc.sh[962]: 2020-02-11 16:06:54Z: Running job: testAction
Feb 11 16:07:10 runner01 runsvc.sh[962]: 2020-02-11 16:07:10Z: Job testAction completed with result: Succeeded
```

--------------------------------

### Example of jobs.<job_id>.steps[*].with

Source: https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions

Defines input parameters for the hello_world action, which are accessible as environment variables prefixed with INPUT_ and converted to upper case.

```yaml
jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: actions/hello_world@main
        with:
          first_name: Mona
          middle_name: The
          last_name: Octocat

```

--------------------------------

### Example of a multiline string (PowerShell)

Source: https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-commands?tool=bash

Sets the JSON_RESPONSE environment variable to the output of an Invoke-WebRequest command using a multiline string with a GUID as delimiter.

```yaml
steps:
  - name: Set the value in pwsh
    id: step_one
    run: |
      $EOF = (New-Guid).Guid
      "JSON_RESPONSE<<$EOF" >> $env:GITHUB_ENV
      (Invoke-WebRequest -Uri "https://example.com").Content >> $env:GITHUB_ENV
      "$EOF" >> $env:GITHUB_ENV
    shell: pwsh
```

--------------------------------

### Example workflow for environment files

Source: https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-commands?tool=bash

Demonstrates setting and using an environment variable across steps using GITHUB_ENV.

```yaml
name: Example Workflow for Environment Files

on: push

jobs:
  set_and_use_env_vars:
    runs-on: ubuntu-latest
    steps:
      - name: Set environment variable
        run: echo "MY_ENV_VAR=myValue" >> $GITHUB_ENV

      - name: Use environment variable
        run: |
          echo "The value of MY_ENV_VAR is $MY_ENV_VAR"

```

--------------------------------

### Example of jobs.<job_id>.steps[*].with

Source: https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax

Defines three input parameters (`first_name`, `middle_name`, `last_name`) for the `hello_world` action. These become environment variables `INPUT_FIRST_NAME`, `INPUT_MIDDLE_NAME`, and `INPUT_LAST_NAME`.

```yaml
jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: actions/hello_world@main
        with:
          first_name: Mona
          middle_name: The
          last_name: Octocat
```

--------------------------------

### Install runner scale set with Helm

Source: https://docs.github.com/en/actions/tutorials/use-actions-runner-controller/get-started

Use this command to install a runner scale set. Replace the placeholder values with your ARC configuration. The installation name is used as the runs-on value in workflows. The namespace determines where runner pods are created. GITHUB_CONFIG_URL is the URL of your repository, organization, or enterprise. GITHUB_PAT is a personal access token (classic) with repo and admin:org scopes. This example installs the latest Helm chart version; use --version to specify a different version.

```bash
INSTALLATION_NAME="arc-runner-set"
NAMESPACE="arc-runners"
GITHUB_CONFIG_URL="https://github.com/<your_enterprise/org/repo>"
GITHUB_PAT="<PAT>"
helm install "${INSTALLATION_NAME}" \
    --namespace "${NAMESPACE}" \
    --create-namespace \
    --set githubConfigUrl="${GITHUB_CONFIG_URL}" \
    --set githubConfigSecret.github_token="${GITHUB_PAT}" \
    oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set
```

--------------------------------

### Example: Specifying an operating system

Source: https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions

This example demonstrates how to specify a GitHub-hosted runner using the `runs-on` keyword with the `ubuntu-latest` label. Use this to run your job on the latest Ubuntu runner provided by GitHub.

```yaml
runs-on: ubuntu-latest

```

--------------------------------

### Run a shell command with the run keyword

Source: https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/add-scripts

Use the `run` keyword to execute a command on the runner. This example runs `npm install -g bats` on an Ubuntu runner.

```yaml
jobs:
  example-job:
    runs-on: ubuntu-latest
    steps:
      - run: npm install -g bats
```

--------------------------------

### Configure Dockerfile and entrypoint.sh script for metadata args

Source: https://docs.github.com/en/actions/reference/workflows-and-actions/dockerfile-support

Sets up a Dockerfile using the exec form of ENTRYPOINT to call entrypoint.sh, which receives and prints the args configured in the action's metadata file.

```dockerfile
# Container image that runs your code
FROM debian:9.5-slim

# Copies your code file from your action repository to the filesystem path `/` of the container
COPY entrypoint.sh /entrypoint.sh

# Executes `entrypoint.sh` when the Docker container starts up
ENTRYPOINT ["/entrypoint.sh"]
```

```shell
#!/bin/sh

# `$#` expands to the number of arguments and `$@` expands to the supplied `args`
printf '%d args:' "$#"
printf " '%s'" "$@"
printf '\n'
```

--------------------------------

### Valid and invalid filter pattern examples in YAML

Source: https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax

Demonstrates correct and incorrect usage of special characters in filter patterns. Patterns starting with `*`, `[`, or `!` must be quoted to avoid YAML parse errors.

```yaml
# Valid
paths:
  - '**/README.md'

# Invalid - creates a parse error that
# prevents your workflow from running.
paths:
  - **/README.md

# Valid
branches: [ main, 'release/v[0-9].[0-9]' ]

# Invalid - creates a parse error
branches: [ main, release/v[0-9].[0-9] ]
```

--------------------------------

### Example: Using fail-fast and continue-on-error together

Source: https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions

This workflow starts four jobs. `continue-on-error` is determined by `matrix.experimental`. If any job with `continue-on-error: false` fails, all in-progress or queued jobs are cancelled. If the job with `continue-on-error: true` fails, other jobs are not affected.

```yaml
jobs:
  test:
    runs-on: ubuntu-latest
    continue-on-error: ${{ matrix.experimental }}
    strategy:
      fail-fast: true
      matrix:
        version: [6, 7, 8]
        experimental: [false]
        include:
          - version: 9
            experimental: true
```

--------------------------------

### Including branches for merge_group event

Source: https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax

Use the `branches` filter to run a workflow only for merge groups targeting specific branches. The patterns are evaluated against the target branch's name. This example runs for a branch named `main` or any branch starting with `releases/`.

```yaml
on:
  merge_group:
    types: [checks_requested]
    branches:
      - main
      - 'releases/**'
```

--------------------------------

### Run a setup script with runs.pre-entrypoint

Source: https://docs.github.com/en/actions/reference/workflows-and-actions/metadata-syntax

Executes a prerequisite setup script before the main entrypoint runs. It runs in a new container instance using the same base image, requiring any shared state to be saved to the workspace, HOME, or a STATE_ variable.

```yaml
runs:
  using: 'docker'
  image: 'Dockerfile'
  args:
    - 'bzz'
  pre-entrypoint: 'setup.sh'
  entrypoint: 'main.sh'
```

--------------------------------

### Including branches for merge_group event

Source: https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions

Use the `branches` filter to run a workflow only for merge groups targeting specific branches. The patterns are evaluated against the target branch's name. This example runs for merge groups targeting `main` or branches starting with `releases/`.

```yaml
on:
  merge_group:
    types: [checks_requested]
    branches:
      - main
      - 'releases/**'

```

--------------------------------

### Cancel a background step using cancel

Source: https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions

Use `cancel` to gracefully terminate a running background step by its `id`. The runner sends `SIGTERM` and then `SIGKILL` if the step does not exit within a grace period. This example starts a long-running monitor in the background, runs the main task, then cancels the monitor.

```yaml
steps:
  - name: Start long-running monitor
    id: monitor
    run: ./scripts/monitor.sh
    background: true

  - name: Run the main task
    run: npm test

  - name: Stop the monitor
    cancel: monitor

```

--------------------------------

### Specify a specific Go version with setup-go

Source: https://docs.github.com/en/actions/tutorials/build-and-test-code/go

Configures actions/setup-go using semantic version syntax to target a specific release range such as '1.21.x'.

```yaml
      - name: Setup Go 1.21.x
        uses: actions/setup-go@v5
        with:
          # Semantic version range syntax or exact version of Go
          go-version: '1.21.x'
```

--------------------------------

### Wait for all background steps using wait-all

Source: https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions

Use `wait-all` to pause the job until all active background steps complete. The step fails if any background step failed, unless `continue-on-error` is set to `true`. This example starts a database and cache in the background, runs integration tests, then waits for all services to stop.

```yaml
steps:
  - name: Start database
    id: db
    run: docker run -d postgres:15
    background: true

  - name: Start cache
    id: cache
    run: docker run -d redis:7
    background: true

  - name: Run integration tests
    run: npm run test:integration

  - name: Wait for all services to stop
    wait-all:

```

--------------------------------

### Example migrate command execution and pull request output

Source: https://docs.github.com/en/actions/tutorials/migrate-to-github-actions/automated-migrations/bitbucket-pipelines-migration

Demonstrates a successful production migration run displaying the log file location and generated pull request URL. Inspect the pull request description for any manual steps before merging.

```bash
gh actions-importer migrate bitbucket --workspace actions-importer --repository custom-trigger --target-url https://github.com/valet-dev-testing/demo-private --output-dir tmp/bitbucket
[2023-07-18 09:56:06] Logs: 'tmp/bitbucket/log/valet-20230718-165606.log'
[2023-07-18 09:56:24] Pull request: 'https://github.com/valet-dev-testing/demo-private/pull/55'
```

--------------------------------

### Example of jobs.<job_id>.steps[*].with.entrypoint

Source: https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions

Overrides the Docker ENTRYPOINT in the Dockerfile, or sets it if not specified. Accepts only a single string defining the executable to run.

```yaml
steps:
  - name: Run a custom command
    uses: octo-org/action-name@main
    with:
      entrypoint: /a/different/executable

```
Tokens:
Raw