Documentation  ❯  Trusted Build Systems   ❯   GitHub

Prerequisites

• Use the predefined Trusted Build System GitHub.com (see configuration)
  • add it to the Organization
  • link it to each SignPath Project for GitHub
• Specify <zip-file> as root element of your Artifact Configurations (GitHub packages all artifacts as ZIP archives)
• Install the SignPath GitHub App and allow access to the code repositories.

GitHub Enterprise

SignPath hosts an instance of the GitHub connector which is linked to GitHub.com For integrating self-hosted GitHub Enterprise instances, contact our support team.

Checks performed by SignPath

The GitHub connector performs the following checks:

• A build was actually performed by a GitHub workflow, not by some other entity in possession of the API token
• Origin metadata is provided by GitHub, not the build script, and can therefore not be forged
• The artifact is stored as a GitHub workflow artifact before it is submitted for signing
• For OSS projects: All jobs of the GitHub worfklow leading up to the signing request were executed on GitHub-hosted agents

Usage

We provide a submit-signing-request action that can be integrated into a GitHub Actions workflow:

steps:
  # required for the artifact to be available on the GitHub server
- name: upload-unsigned-artifact
  id: upload-unsigned-artifact
  uses: actions/upload-artifact@v4
  with: 
    path: path/to/your/artifact

- id: optional_step_id
  uses: signpath/github-action-submit-signing-request@v1.1
  with:
    api-token: '${{ secrets.SIGNPATH_API_TOKEN }}'
    organization-id: '<SignPath organization id>'
    project-slug: '<SignPath project slug>'
    signing-policy-slug: '<SignPath signing policy slug>'
    github-artifact-id: '${{ steps.upload-unsigned-artifact.outputs.artifact-id }}'
    wait-for-completion: true
    output-artifact-directory: '/path/to/signed/artifact/directory'

Action input parameters

Action output parameters

The action supports the following output parameters:

• signing-request-id: The id of the newly created signing request
• signing-request-web-url: The url of the signing request in SignPath
• signpath-api-url: The base API url of the SignPath API
• signed-artifact-download-url: The url of the signed artifact in SignPath

Define policies for source code and builds

Available for Advanced Code Signing, Code Signing Gateway.

You can define specific source code and build policies for your repository per signing policy:

• runners: define which runners may be used by GitHub Actions
• build: define conditions for GitHub Actions workflows and runs
• branch_rulesets: define minimum requirements for branch rulesets including conditions for integrity, reviews, and code scanning

Steps to create a policy file:

• create the policy file in the default branch of the source code repository
• name it .signpath/policies/<project-slug>/<signing-policy-slug>.yml
• restrict write permissions to the policy files using GitHub’s code owners feature

Policy sections

runners section

Use the runners section to define which runners may be used in the workflow run.

build section

Use the build section to configure rules for the build run.

branch_rulesets section

Use the branch_rulests section to configure conditions for GitHub branch rulesets.

• You can configure branch rulesets in GitHub on an organization or repository level. SignPath verifies that there is at least one branch ruleset for each specified condition.
• Rules define minimum requirements that may be exceeded by the actual branch ruleset.

How branch_rulesets conditions are evaluated

You can group your policy requirements into multiple conditions, each containing a combination of rules, bypassers, and enforcement date:

About enforced_from evaluation

Depending on your GitHub subscription, the continuous enforcement of policies is either based on:

• Audit log events for GitHub Enterprise subscriptions. Audit log events are only available for the last 180 days, any prior policy violations will not be detected.
• The last modified date of the branch rulesets for all other subscriptions. At least one branch ruleset that has not been modified since the specified timestap must implement the rule.

Available branch_rulesets rules

Example

# .signpath/policies/my-project-slug/release-signing.yml

github-policies:
  runners:
    allowed_groups:
      - 'GitHub Actions'                         # all jobs need to run on GitHub-hosted runners
  build:
    disallow_reruns: true
  branch_rulesets:
    - condition:
        rules:
        - block_force_pushes:                    # force pushes are prevented
        - pull_request:                          # code reviews are required
            min_required_approvals: 1
            require_code_owner_review: true
      allow_bypass_actors: false                 # no-one is allowed to bypass this rule
      enforced_from: EARLIEST                    # rule enforcement history is checked
    - condition:
        rules:
        - require_code_scanning:                 # code scanning must not reveal problems
            tools:
              - tool: CodeQL
                min_alerts_threshold: errors
                min_security_alerts_threshold: medium
        allow_bypass_actors: true                # some people may bypass these rules
        enforced_from: '2025-01-01 00:00'        # had to be reset at some point