## GitHub Actions Overview

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 use GitHub Actions to include Endor Labs into your CI pipeline seamlessly. Using this pipeline, developers can view and detect:

- Policy violations in the source code
- Secrets inadvertently included in the source code

The Endor Labs verifications are conducted as automated checks and help you discover violations before pushing code to the repository. Information about the violations can be included as comments on the corresponding pull request (PR). This enables developers to easily identify issues and take remedial measures early in the development life cycle.

- For policy violations, the workflow is designed to either emit a warning or return an error based on your action policy configurations.
- For secrets discovered in the commits, developers can view the PR comments and take necessary remedial measures.

## Install Software Prerequisites

To ensure the successful execution of the Endor Labs GitHub action, the following prerequisites must be met:

- The GitHub action must be able to authenticate with the Endor Labs API.
- You must have the value of the Endor Labs namespace handy for authentication.
- You must have access to the Endor Labs API.
- If you use keyless authentication, you must set an authorization policy in Endor Labs. See [Authorization policies](https://docs.endorlabs.com/platform-administration/rbac/authorization-policies) for details.

## Secure GitHub Actions with immutable commit SHA

Endor Labs recommends pinning the commit SHA of the GitHub Actions to enhance security. By pinning GitHub Actions to a commit SHA, you make the code immutable even if the tag version is changed or the code is updated.

### Latest GitHub Action Release

Pin to an immutable commit SHA for enhanced security.

```bash
endorlabs/github-action@f46ffb04c928a9c9c356f9627bd60b710ed0963e # v1.1.13
```

To manually find the Endor Labs GitHub action’s latest commit SHA:

1. Go to [Endor Labs GitHub Actions](https://github.com/endorlabs/github-action) and select the latest release version in **Releases**.
2. Click the commit of the release.
3. Copy the commit SHA from the URL. The commit SHA is the 40-character alphanumeric string in the URL after `/commit/`.

## Example GitHub Action Workflow

Endor Labs scanning workflow using GitHub Actions that accomplishes the following tasks in your CI environment:

- Tests PRs to the default branch and monitors the most recent push to the default branch.
- Builds a Java project and sets up the Java build tools. If your project is not on Java, then configure this workflow with your project-specific steps and build tools.
- Authenticates to Endor Labs with GitHub Actions keyless authentication.
- Scan with Endor Labs.
- Comments on PRs if any policy violations occur.
- Generates findings and uploads results to GitHub in SARIF format.

```yaml
name: Endor Labs Dependency and Secrets Scan
on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]
jobs:
  scan:
    permissions:
      security-events: write # Used to upload Sarif artifact to GitHub
      contents: read # Used to check out a private repository
      actions: read # Required for private repositories to upload Sarif files. GitHub Advanced Security licenses are required.
      id-token: write # Used for keyless authentication with Endor Labs
      pull-requests: write # Required to automatically comment on PRs for new policy violations
      issues: write # Required to comment on PRs for new policy violations
    runs-on: ubuntu-latest
    steps:
    - name: Checkout Repository
      uses: actions/checkout@v3
    - name: Setup Java
      uses: actions/setup-java@v3
      with:
        distribution: 'microsoft'
        java-version: '17'
    - name: Build Package
      run: mvn clean install
    - name: Endor Labs Scan Pull Request
      if: github.event_name == 'pull_request'
      uses: endorlabs/github-action@b8992820cc4d9c9e7ded5022adf6cabe2dc11946 # v1.1.12
      with:
        namespace: 'example' # Replace with your Endor Labs tenant namespace
        scan_dependencies: true
        scan_secrets: true
        pr: true
        pr_incremental: true # Scans only files and dependencies that changed, for faster PR scans
        enable_pr_comments: true # Required to automatically comment on PRs for new policy violations
        github_token: ${{ secrets.GITHUB_TOKEN }} # Required for PR comments on new policy violations

scan-main:
    permissions:
      id-token: write
      repository-projects: read
      pull-requests: read
      contents: read
    name: endorctl-scan
    runs-on: ubuntu-latest
    steps:
    - name: Checkout Repository
      uses: actions/checkout@v3
    - name: Setup Java
      uses: actions/setup-java@v3
      with:
        distribution: 'microsoft'
        java-version: '17'
    - name: Build Package
      run: mvn clean install
    - name: 'Endor Labs Scan Push to main'
      if: ${{ github.event_name == 'push' }}
      uses: endorlabs/github-action@b8992820cc4d9c9e7ded5022adf6cabe2dc11946 # v1.1.12
      with:
        namespace: 'example' # Replace with your Endor Labs tenant namespace
        scan_dependencies: true
        scan_secrets: true
        pr: false
        scan_summary_output_type: 'table'
        sarif_file: 'findings.sarif'
    - name: Upload findings to github
      uses: github/codeql-action/upload-sarif@v3
      with:
        sarif_file: 'findings.sarif'
```

A policy violation makes the scan exit with a non-zero code, which fails the job. Failing the job does not block a merge on its own. To block pull requests, mark the scan job as a required status check in GitHub.

## Set up branch tracking in GitHub Actions

In Git, a detached HEAD state occurs when the repository checks out a specific commit instead of a branch reference. In this state, Git points the HEAD directly to a commit hash, without associating it with a named branch. Proper branch context enables Endor Labs to:

- Associate scans with the correct branch
- Identify scans on the monitored default branch
- Track findings and display metrics accurately across branches

Without proper branch configuration, Endor Labs may create multiple branch entries for the same logical branch, leading to fragmented reporting and inaccurate metrics.

## Scan containers with OS reachability

You can use the Endor Labs GitHub Action to scan container images with [OS reachability](https://docs.endorlabs.com/scan/containers/container-reachability) enabled. Container reachability identifies which packages inside a container image are actually used at runtime, helping you prioritize the most critical vulnerabilities for remediation. Set `scan_container: true` and `os_reachability: true` to enable container scanning with reachability analysis:

```yaml
    - name: Scan container with OS reachability
      uses: endorlabs/github-action@b8992820cc4d9c9e7ded5022adf6cabe2dc11946 # v1.1.12
      with:
        namespace: 'example'
        enable_github_action_token: 'true'
        scan_container: true
        scan_dependencies: false
        image: "nginx:latest"
        os_reachability: true
        pr: false
        project_name: 'my-project'
```

## Authenticate with Endor Labs

Endor Labs recommends using keyless authentication in CI environments. Keyless authentication is more secure and reduces the cost of secret rotation. To set up keyless authentication see [Keyless Authentication](https://docs.endorlabs.com/setup-deployment/ci-cd/keyless-authentication). If you choose not to use keyless authentication, you can configure an API key and secret in GitHub for authentication as outlined in [Managing API keys](https://docs.endorlabs.com/platform-administration/api-keys).

### Authentication Without Keyless Authentication for GitHub

If you are not using keyless authentication for GitHub Actions, you must not provide `id-token: write` permissions to your GitHub token unless specifically required by a step in this job. You must also set `enable_github_action_token: false` in your Endor Labs GitHub Action configuration. The following example configuration uses the Endor Labs API key for authentication:

```yaml
      - name: Scan with Endor Labs
        uses: endorlabs/github-action@b8992820cc4d9c9e7ded5022adf6cabe2dc11946 # v1.1.12
        with:
          namespace: 'example'
          api_key: ${{ secrets.ENDOR_API_CREDENTIALS_KEY }}
          api_secret: ${{ secrets.ENDOR_API_CREDENTIALS_SECRET }}
          enable_github_action_token: false
```

## Endor Labs GitHub Action Configuration Parameters

The following input configuration parameters are supported for the Endor Labs GitHub Action:

### Common parameters

| Flags                                 | Description                                                   |
|---------------------------------------|---------------------------------------------------------------|
| `api`                                 | Set the Endor Labs API to use.                              |
| `api_key`                            | Set the API key used to authenticate with Endor Labs.       |
| `api_secret`                         | Set the secret corresponding to the API key used.           |
| `enable_github_action_token`         | Set to `false` for alternative authentication methods.        |
| `namespace`                          | Set to the namespace of the project you are working with.   |

### Scanning parameters

| Flags                     | Description                                                   |
|--------------------------|---------------------------------------------------------------|
| `scan_dependencies`      | Scan Git commits and generate findings for all dependencies. |
| `scan_secrets`          | Scan the source code repo for secrets.                       |
| `scan_container`        | Scan a specified container image.                            |
| `os_reachability`       | Enable OS reachability analysis for container scans.         |

### Artifact scanning parameters

Use the following parameters and the latest sign action to build artifact signing through Endor Labs GitHub Actions.

Latest Sign action — pin to commit SHA

```bash
endorlabs/github-action/sign@f46ffb04c928a9c9c356f9627bd60b710ed0963e # v1.1.13
```

| Flags                      | Required  | Description                                |
|----------------------------|-----------|--------------------------------------------|
| `artifact_name`            | Mandatory | Name of the artifact to be signed.        |
| `source_repository_ref`    | Optional  | Repository reference for the build run.   |
| `certificate_oidc_issuer`  | Optional  | OIDC issuer of the expected token.        |

### Artifact verifying parameters

Use the following verification parameters and the latest verify action to build artifact verification through Endor Labs GitHub Actions.

Latest Verify action — pin to commit SHA

```bash
endorlabs/github-action/verify@f46ffb04c928a9c9c356f9627bd60b710ed0963e # v1.1.13
```

| Flags                        | Required  | Description                                  |
|------------------------------|-----------|----------------------------------------------|
| `artifact_name`              | Mandatory | Name of the artifact to be verified.        |
| `certificate_oidc_issuer`    | Mandatory | OIDC issuer expected in the certificate.    |