Skip to content

github-emu.md

Latest commit

 

History

History
499 lines (385 loc) · 15.6 KB

github-emu.md

File metadata and controls

499 lines (385 loc) · 15.6 KB

GitHub Enterprise Managed Users (EMU)

This guide covers using the actions-dependency-submission action on GitHub Enterprise Cloud with Enterprise Managed Users (EMU).

Overview

EMU environments often have forked actions from public GitHub (github.com) that have been mirrored to your EMU instance. This action needs:

  1. A token with contents: write permission to submit dependencies to your EMU instance
  2. Optionally, a token with contents: read permission to public GitHub to look up original repositories for forked actions
  3. If your workflows reference private or internal actions, the primary token needs contents: read permission on those repositories

Token Options

Primary Token (Required)

The primary token is used to submit dependencies and access your EMU instance.

Option 1: Workflow Token (Recommended for EMU)

The built-in GITHUB_TOKEN is the simplest and most secure option.

Workflow Token Example
name: Submit Dependencies
on:
  push:
    branches: [main]
  schedule:
    - cron: '0 0 * * 0' # Weekly

jobs:
  submit-dependencies:
    runs-on: ubuntu-latest
    permissions:
      contents: write # Required for dependency submission
    steps:
      - uses: actions/checkout@v4
      - uses: jessehouwing/actions-dependency-submission@v1
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          fork-organizations: 'myenterprise'
Workflow Token Advantages
  • ✅ Automatic: No setup required, automatically available
  • ✅ Secure: Token is scoped to the workflow run and expires automatically
  • ✅ No maintenance: No need to rotate or manage credentials
  • ✅ Audit trail: Actions are attributed to the GitHub Actions bot
Workflow Token Disadvantages
  • ❌ Repository scoped: Cannot access private/internal actions in other repositories by default
  • ❌ No public GitHub access: Cannot look up actions on public GitHub
When to Use Workflow Token

Use the workflow token when:

  • You only use actions mirrored to your EMU instance (no public GitHub lookups needed)
  • Your workflows only use local composite actions within the same repository
  • You have fork-regex configured and all forked actions exist locally on your EMU instance
Additional Configuration for Private/Internal Actions

If your workflows reference private or internal actions in other repositories, configure access via Allowing access to components in a private repository.

Once configured, the GITHUB_TOKEN will have contents: read access to those repositories.

Option 2: GitHub App Token

A GitHub App provides flexibility for accessing multiple repositories and better audit trails.

GitHub App Setup
  1. Create a GitHub App in your EMU organization
  2. Configure the app with these permissions:
    • Repository permissions:
      • Contents: Read and Write
  3. Install the app on:
    • The repository where you're submitting dependencies
    • Any repositories containing private/internal actions you reference
  4. Note the App ID and generate a private key
GitHub App Example
name: Submit Dependencies
on:
  push:
    branches: [main]
  schedule:
    - cron: '0 0 * * 0' # Weekly

jobs:
  submit-dependencies:
    runs-on: ubuntu-latest
    permissions:
      contents: read # Only needed if checking out code
    steps:
      - uses: actions/checkout@v4

      - name: Generate token
        id: generate-token
        uses: actions/create-github-app-token@v1
        with:
          app-id: ${{ secrets.APP_ID }}
          private-key: ${{ secrets.APP_PRIVATE_KEY }}
          repositories: |
            my-repo
            my-private-actions

      - uses: jessehouwing/actions-dependency-submission@v1
        with:
          token: ${{ steps.generate-token.outputs.token }}
          fork-organizations: 'myenterprise'
GitHub App Advantages
  • ✅ Organization-wide: Can be installed across multiple repositories
  • ✅ Fine-grained permissions: Limit access to specific repositories
  • ✅ Better audit trail: Actions are attributed to the app
  • ✅ No user account dependency: Not tied to a specific user
  • ✅ Cross-repository access: Can access private/internal actions
GitHub App Disadvantages
  • ⚠️ Setup complexity: Requires creating and configuring a GitHub App
  • ⚠️ Key management: Need to securely store app private key
  • ⚠️ No public GitHub access: Cannot look up actions on public GitHub
When to Use GitHub App

Use a GitHub App token when:

  • You need to access multiple repositories
  • Your workflows reference private/internal actions in other repositories
  • You want better audit trails
  • You need organization-wide dependency submission

Option 3: Personal Access Token

A personal access token can be used when GitHub Apps are not an option.

PAT Setup
  1. Create a Fine-grained Personal Access Token (recommended)
  2. Configure with:
    • Repository access: Select repositories or all repositories
    • Permissions:
      • Contents: Read and Write
  3. Store as a repository secret (e.g., DEPENDENCY_SUBMISSION_TOKEN)
PAT Example
name: Submit Dependencies
on:
  push:
    branches: [main]
  schedule:
    - cron: '0 0 * * 0' # Weekly

jobs:
  submit-dependencies:
    runs-on: ubuntu-latest
    permissions:
      contents: read # Only needed if checking out code
    steps:
      - uses: actions/checkout@v4
      - uses: jessehouwing/actions-dependency-submission@v1
        with:
          token: ${{ secrets.DEPENDENCY_SUBMISSION_TOKEN }}
          fork-organizations: 'myenterprise'
PAT Advantages
  • ✅ Simple setup: Easy to create and configure
  • ✅ Flexible: Can access multiple repositories
  • ✅ Cross-repository access: Can access private/internal actions
PAT Disadvantages
  • ⚠️ Security risk: Long-lived, doesn't expire automatically
  • ⚠️ User-dependent: Tied to a specific user account
  • ⚠️ Manual rotation: Must be manually rotated
  • ⚠️ No public GitHub access: Cannot look up actions on public GitHub

⚠️ Security Warning: Personal access tokens are less secure than GitHub Apps. Consider using a GitHub App token instead.

Public GitHub Token (Optional)

When your EMU instance has forked actions without maintaining GitHub fork relationships, you need a token to look up the original repositories on public GitHub (github.com).

Setup Options

Option A: GitHub App Token for Public GitHub (Recommended)

Create a separate GitHub App on public GitHub (github.com) for looking up action repositories.

Public GitHub App Setup
  1. Create a GitHub App on public GitHub (github.com)
  2. Configure with minimal permissions:
    • Repository permissions:
      • Contents: Read (for public repositories)
      • Metadata: Read (automatically included)
  3. Install the app on public repositories you need to access (or make it public)
  4. Store the App ID and private key as secrets
Public GitHub App Example
name: Submit Dependencies
on:
  push:
    branches: [main]
  schedule:
    - cron: '0 0 * * 0' # Weekly

jobs:
  submit-dependencies:
    runs-on: ubuntu-latest
    permissions:
      contents: write # Required for dependency submission
    steps:
      - uses: actions/checkout@v4

      - name: Generate public GitHub token
        id: generate-public-token
        uses: actions/create-github-app-token@v1
        with:
          app-id: ${{ secrets.PUBLIC_GITHUB_APP_ID }}
          private-key: ${{ secrets.PUBLIC_GITHUB_APP_PRIVATE_KEY }}
          # This app is on public GitHub, not your EMU instance
          github-api-url: https://api.github.com

      - uses: jessehouwing/actions-dependency-submission@v1
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          fork-organizations: 'myenterprise'
          public-github-token: ${{ steps.generate-public-token.outputs.token }}
Public GitHub App Advantages
  • ✅ Secure: Short-lived tokens that auto-expire
  • ✅ Fine-grained: Only needs read access to public repositories
  • ✅ Better audit trail: Actions attributed to the app
  • ✅ Automatic rotation: Tokens are generated on-demand
Public GitHub App Disadvantages
  • ⚠️ Setup complexity: Requires creating an app on public GitHub
  • ⚠️ Key management: Need to securely store app private key
  • ⚠️ Additional step: Requires an extra workflow step
Option B: Personal Access Token for Public GitHub

Create a personal access token on public GitHub (github.com) for read-only access to public repositories.

Public GitHub PAT Setup
  1. Create a Fine-grained Personal Access Token on public GitHub (github.com)
  2. Configure with:
    • Repository access: Public Repositories (read-only)
    • Permissions:
      • Contents: Read
      • Metadata: Read
  3. Store as a repository secret (e.g., PUBLIC_GITHUB_TOKEN)
Public GitHub PAT Example
name: Submit Dependencies
on:
  push:
    branches: [main]
  schedule:
    - cron: '0 0 * * 0' # Weekly

jobs:
  submit-dependencies:
    runs-on: ubuntu-latest
    permissions:
      contents: write # Required for dependency submission
    steps:
      - uses: actions/checkout@v4
      - uses: jessehouwing/actions-dependency-submission@v1
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          fork-organizations: 'myenterprise'
          public-github-token: ${{ secrets.PUBLIC_GITHUB_TOKEN }}
Public GitHub PAT Advantages
  • ✅ Simple setup: Easy to create
  • ✅ Read-only access: Limited to reading public repositories
Public GitHub PAT Disadvantages
  • ⚠️ Security risk: Long-lived token that doesn't expire automatically
  • ⚠️ User-dependent: Tied to a personal GitHub.com account
  • ⚠️ Manual rotation: Must be manually rotated
  • ⚠️ Audit trail: Actions attributed to the user

⚠️ Security Warning: Personal access tokens are less secure because they:

  • Don't expire automatically
  • Are tied to a user account
  • Must be manually rotated
  • Can be used indefinitely if compromised

Recommendation: Use a GitHub App token instead for better security.

Complete Examples

Example 1: EMU with Workflow Token and Regular Expression Pattern

Best for when forked actions follow a naming convention and you don't need to look up actions on public GitHub.

name: Submit Dependencies
on:
  push:
    branches: [main]
  schedule:
    - cron: '0 0 * * 0' # Weekly

jobs:
  submit-dependencies:
    runs-on: ubuntu-latest
    permissions:
      contents: write # Required for dependency submission
    steps:
      - uses: actions/checkout@v4
      - uses: jessehouwing/actions-dependency-submission@v1
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          fork-organizations: 'myenterprise'
          fork-regex: '^myenterprise/(?<org>[^_]+)_(?<repo>.+)'

In this example:

  • myenterprise/actions_checkout resolves to actions/checkout using the regular expression pattern
  • This simplifies repository name resolution but still requires a public GitHub token to look up tags from commit SHAs on the parent repository

Example 2: EMU with GitHub App Tokens (Most Secure)

Best for production environments requiring maximum security and audit trails.

name: Submit Dependencies
on:
  push:
    branches: [main]
  schedule:
    - cron: '0 0 * * 0' # Weekly

jobs:
  submit-dependencies:
    runs-on: ubuntu-latest
    permissions:
      contents: read # Only needed for checkout
    steps:
      - uses: actions/checkout@v4

      - name: Generate EMU token
        id: generate-emu-token
        uses: actions/create-github-app-token@v1
        with:
          app-id: ${{ secrets.EMU_APP_ID }}
          private-key: ${{ secrets.EMU_APP_PRIVATE_KEY }}

      - name: Generate public GitHub token
        id: generate-public-token
        uses: actions/create-github-app-token@v1
        with:
          app-id: ${{ secrets.PUBLIC_GITHUB_APP_ID }}
          private-key: ${{ secrets.PUBLIC_GITHUB_APP_PRIVATE_KEY }}
          github-api-url: https://api.github.com

      - uses: jessehouwing/actions-dependency-submission@v1
        with:
          token: ${{ steps.generate-emu-token.outputs.token }}
          fork-organizations: 'myenterprise'
          public-github-token: ${{ steps.generate-public-token.outputs.token }}

Example 3: EMU with Mixed Tokens

Workflow token for EMU, GitHub App for public GitHub lookups.

name: Submit Dependencies
on:
  push:
    branches: [main]
  schedule:
    - cron: '0 0 * * 0' # Weekly

jobs:
  submit-dependencies:
    runs-on: ubuntu-latest
    permissions:
      contents: write # Required for dependency submission
    steps:
      - uses: actions/checkout@v4

      - name: Generate public GitHub token
        id: generate-public-token
        uses: actions/create-github-app-token@v1
        with:
          app-id: ${{ secrets.PUBLIC_GITHUB_APP_ID }}
          private-key: ${{ secrets.PUBLIC_GITHUB_APP_PRIVATE_KEY }}
          github-api-url: https://api.github.com

      - uses: jessehouwing/actions-dependency-submission@v1
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          fork-organizations: 'myenterprise'
          public-github-token: ${{ steps.generate-public-token.outputs.token }}

Permissions Summary

Token Purpose Minimum Permissions
Primary Token Submit dependencies to EMU contents: write
Primary Token Access private/internal actions contents: read (automatic)
Public GitHub Token Look up actions on GitHub.com contents: read (public repos)

Best Practices

  1. Always define permissions at the job level for least privilege
  2. Use GitHub Apps for both tokens when possible for maximum security
  3. Use regular expression patterns to simplify repository name resolution (note: a public GitHub token is still required to look up tags from commit SHAs)
  4. Regularly audit public GitHub token usage and permissions
  5. Document your fork naming conventions if using regular expression patterns
  6. Monitor for actions that cannot be resolved and may need manual mapping
  7. Configure access to private/internal action repositories via repository settings

Documentation