GitHub Actions Documentation

website·Indexed 32 days ago

https://docker-deploy.cssnr.com

Guides and reference for automating software workflows. Covers workflow syntax, event triggers, secret management, security best practices for mitigating script injection, and managing workflow run logs.

Tokens: 13.8K
Snippets: 63
Records: 105
Agent score: 50%

What's inside GitHub Actions

Understand GitHub organization accounts
GitHub organizations are shared accounts that act as containers for shared work, providing a unique name and brand for businesses or open-source projects. They allow multiple personal accounts to collaborate on projects. Access is managed by organization owners who can assign roles to members to control access to the organization's resources, repositories, projects, and apps. To simplify management, organizations support nested teams with cascading permissions.
https://docs.github.com/en/organizations/collaborating-with-groups-in-organizations/about-organizationswebsitellms
Understand GitHub Actions workflow basics
A GitHub Actions workflow is a configurable automated process defined by a YAML file located in the .github/workflows directory of a repository. A workflow consists of three primary components:
1. Events: Triggers that start the workflow.
2. Jobs: Execution units that run on a runner machine. Each job contains one or more steps.
3. Steps: Individual tasks within a job that either execute a custom script or a reusable action.
https://docs.github.com/en/actions/concepts/workflows-and-actions/workflowswebsitellms
Manage and communicate vulnerability fixes using the Dependents view
When a vulnerability is reported in your code, use the Dependents view in the Dependency graph to identify which projects depend on your code. This allows you to determine who needs to be notified about the vulnerability and coordinate the necessary fixes.
https://docs.github.com/en/actions/reference/security/secure-usewebsitellms
Create organization secrets via GitHub Web UI
Organization owners can create secrets at the organization level and define access policies to limit which repositories can use them (e.g., all repositories, only private repositories, or a selected list).
Steps:
1. Navigate to the organization's main page.
2. Go to Settings.
3. In the "Security" sidebar section, select Secrets and variables > Actions.
4. Click the Secrets tab and select New organization secret.
5. Provide a Name and Value.
6. Select a Repository access policy from the dropdown.
7. Click Add secret.
https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/use-secretswebsitellms
Run jobs based on the conclusion of a triggering workflow
The workflow_run event triggers regardless of whether the previous workflow succeeded or failed. To execute specific jobs based on the outcome, use a conditional check against the github.event.workflow_run.conclusion property. Common values for the conclusion are success and failure.
```
on:
  workflow_run:
    workflows: [Build]
    types: [completed]

jobs:
  on-success:
    runs-on: ubuntu-latest
    if: ${{ github.event.workflow_run.conclusion == 'success' }}
    steps:
      - run: echo 'The triggering workflow passed'
  on-failure:
    runs-on: ubuntu-latest
    if: ${{ github.event.workflow_run.conclusion == 'failure' }}
    steps:
      - run: echo 'The triggering workflow failed'
```
https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflowswebsitellms

Access artifacts from a triggering workflow

A workflow triggered by workflow_run can access data or artifacts produced by the triggering workflow. This is achieved by using the github.event.workflow_run.id to identify the specific run from which to download artifacts via the actions/download-artifact action.

# Triggering Workflow: Uploads artifact
name: Upload data
on: [pull_request]
jobs:
  upload:
    runs-on: ubuntu-latest
    steps:
      - run: |
          mkdir -p ./pr
          echo "${{ github.event.number }}" > ./pr/pr_number
      - uses: actions/upload-artifact@v4
        with:
          name: pr_number
          path: pr/

# Dependent Workflow: Downloads and uses artifact
name: Use the data
on:
  workflow_run:
    workflows: [Upload data]
    types: [completed]
jobs:
  download:
    runs-on: ubuntu-latest
    permissions:
      actions: read
      issues: write
    steps:
      - name: 'Download artifact'
        uses: actions/download-artifact@v5
        with:
          name: pr_number
          path: ${{ runner.temp }}/artifacts
          run-id: ${{ github.event.workflow_run.id }}
          github-token: ${{ secrets.GITHUB_TOKEN }}

Screen action changes in Pull Requests using Dependency Review
To evaluate the security impact of adding or updating actions in a workflow, use dependency review during the pull request process. This provides a visualization of added, removed, or updated dependencies, their release dates, usage statistics, and vulnerability data. The dependency-review-action can be integrated into workflows to automatically scan for and warn about vulnerable versions of dependencies introduced in a PR.
```
# Use the dependency-review-action in your workflow to enforce reviews
- uses: actions/dependency-review-action@main
```
https://docs.github.com/en/actions/reference/security/secure-usewebsitellms
Secure workflow dependencies with OpenSSF Scorecards
Use the OpenSSF Scorecards action and workflow templates to automatically detect risky supply chain practices in your GitHub Actions workflows. Scorecards runs checks for script injection attacks, token permissions, and pinned actions, alerting developers through the built-in code scanning experience.
https://docs.github.com/en/actions/reference/security/secure-usewebsitellms
Create repository secrets via GitHub Web UI
To create secrets for a repository, you must have write access for organization repositories or be a repository collaborator for personal account repositories.
Steps to create a secret:
1. Navigate to the repository main page.
2. Click Settings (or the kebab menu $\rightarrow$ Settings).
3. In the "Security" section of the sidebar, select Secrets and variables $\rightarrow$ Actions.
4. Click the Secrets tab.
5. Click New repository secret.
6. Enter a Name and the Secret value.
7. Click Add secret.
https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/use-secretswebsitellms

Pass secrets to shell commands securely

Avoid passing secrets directly as command-line arguments to prevent them from being visible in process lists (e.g., ps command) or security audits. Instead, map the secret to an environment variable and reference that variable using the shell's specific quoting rules to handle special characters.

# Bash example
steps:
  - shell: bash
    env:
      SUPER_SECRET: ${{ secrets.SuperSecret }}
    run: |
      example-command "$SUPER_SECRET"

# PowerShell example
steps:
  - shell: pwsh
    env:
      SUPER_SECRET: ${{ secrets.SuperSecret }}
    run: |
      example-command "$env:SUPER_SECRET"

# Cmd.exe example
steps:
  - shell: cmd
    env:
      SUPER_SECRET: ${{ secrets.SuperSecret }}
    run: |
      example-command "%SUPER_SECRET%"

Manually run a workflow via the GitHub Web UI
1. Navigate to the main page of the repository on GitHub.
2. Click the Actions tab.
3. Select the specific workflow from the left sidebar.
4. Click the Run workflow button (this button only appears if the workflow uses the workflow_dispatch event).
5. Select the desired Branch from the dropdown menu.
6. Fill in any required input fields.
7. Click Run workflow.
https://docs.github.com/en/actions/how-tos/manage-workflow-runs/manually-run-a-workflowwebsitellms

Store small binary blobs as Base64 secrets in GitHub Actions

Small binary files (like certificates) can be stored as GitHub secrets by encoding them into Base64 strings. Note that Base64 is encoding, not encryption. On Windows runners, it is recommended to use shell: bash to ensure compatibility with the base64 command.

# Encode file to Base64
# macOS
base64 -i cert.der -o cert.base64
# Linux
base64 -w 0 cert.der > cert.base64

# Set the secret using GitHub CLI
gh secret set CERTIFICATE_BASE64 < cert.base64

# Workflow snippet to decode the secret
steps:
  - uses: actions/checkout@v6
  - name: Retrieve the secret and decode it to a file
    env:
      CERTIFICATE_BASE64: ${{ secrets.CERTIFICATE_BASE64 }}
    run: |
      echo $CERTIFICATE_BASE64 | base64 --decode > cert.der