Managing Organization Workflows

1. Creating Organization Starter Workflows

Starter workflows are reusable, customizable workflow templates that help you get started with GitHub Actions. They can be shared across an organization to ensure consistency and reduce setup time.

Field	Description	Example
name	Name of the starter workflow	`CI`
description	Description of the starter workflow	`Continuous Integration workflow`
icon	Icon to represent the workflow (optional)	`circle`
categories	Categories to help organize the starter workflow	`[ci, cd]`
file-name	Name of the file in the `.github/workflows` directory	`starter-workflow.yml`

Example: Creating a Starter Workflow

name: CI
description: Continuous Integration workflow
icon: circle
categories:
  - ci
  - cd
file-name: starter-workflow.yml

Note: Starter workflows must be defined in the .github repository within your organization.

Warning: Once a starter workflow is created, it cannot be deleted or renamed.

Property	Description	Values
uses	Specifies the reusable workflow to use	`owner/repo/.github/workflows/workflow.yml@ref`
with	Input parameters to pass to the reusable workflow	Object with key-value pairs
secrets	Secrets to pass to the reusable workflow	Object with key-value pairs

Example: Using a Reusable Workflow

name: Reusable Workflow Example
on:
  push:
    branches: [ main ]
jobs:
  use-workflow:
    uses: octocat/shared-workflows/.github/workflows/build.yml@v1
    with:
      environment: production
    secrets:
      token: ${{ secrets.GITHUB_TOKEN }}

Note: Reusable workflows must be stored in the .github/workflows directory of a repository.

Key Points

Reusable workflows allow sharing common workflow logic across repositories
Use the uses keyword to reference a reusable workflow
Pass parameters using with and secrets using secrets
Reusable workflows must be stored in the .github/workflows directory

3. Setting Required Workflows

Required workflows ensure that specific GitHub Actions workflows run on all branches and pull requests in a repository. This is particularly useful for enforcing security checks, code quality standards, or compliance requirements.

Setting	Description	Value
required_workflows	Lists the workflows that must run before a branch can be merged	`["security-checks.yml", "code-quality.yml"]`

Example: Configuring Required Workflows

name: Required Workflows
on:
  pull_request:
    branches: [ main ]
jobs:
  enforce-required-workflows:
    runs-on: ubuntu-latest
    steps:
      - name: Check Required Workflows
        uses: actions/required-workflows@v1
        with:
          required_workflows: |
            security-checks.yml
            code-quality.yml

Note: Required workflows must be defined in the repository's .github/workflows directory and are enforced at the branch protection level.

Warning: If a required workflow fails, the pull request cannot be merged until it is fixed.

4. Using Organization Secrets

Secret Name	Value	Usage	Notes
ORG_SECRET_NAME	`secret-value-here`	In workflow YAML using `${{ secrets.ORG_SECRET_NAME }}`	Accessible to all repos in the organization

Example: Using Organization Secret in a Workflow

name: Secure Workflow
on:
  push:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Use secret
        run: echo ${{ secrets.ORG_SECRET_NAME }}

Note: Organization secrets are encrypted and stored securely by GitHub.

Warning: Never hardcode secrets in your workflow files.

5. Managing Runner Groups

Property	Description	Values
runner-group.name	Name of the runner group	`my-runner-group`
runner-group.runners	List of runner IDs assigned to the group	`[1, 2, 3]`
runner-group.default	Whether this is the default group for new runners	`false`

Example: Create a Runner Group

name: Create Runner Group
on:
  workflow_dispatch:

jobs:
  create-runner-group:
    runs-on: ubuntu-latest
    steps:
      - name: Create Runner Group
        run: |
          gh api \
            --method POST \
            -H "Accept: application/vnd.github+json" \
            -H "Authorization: Bearer ${{ secrets.GITHUB_TOKEN }}" \
            /orgs/ORG_NAME/runner-groups \
            -f name="my-runner-group" \
            -f runners=[1,2,3] \
            -f default=false

Example: Update Runner Group

name: Update Runner Group
on:
  workflow_dispatch:

jobs:
  update-runner-group:
    runs-on: ubuntu-latest
    steps:
      - name: Update Runner Group
        run: |
          gh api \
            --method PATCH \
            -H "Accept: application/vnd.github+json" \
            -H "Authorization: Bearer ${{ secrets.GITHUB_TOKEN }}" \
            /orgs/ORG_NAME/runner-groups/123 \
            -f name="updated-runner-group" \
            -f runners=[4,5,6]

Note: Runner groups can only be managed via the GitHub API or CLI. There is no direct UI in the GitHub web interface for managing runner groups.

6. Configuring Organization Policies

Policy	Description	Configuration	Notes
workflow permissions	Controls the permissions for workflows in the organization	`read`, `write`, `admin`	Defaults to `read` for public repos, `write` for private
allowed actions	Specifies which actions are allowed in workflows	`all`, `read`, `write`	Can restrict to `github` or custom actions
allowed runners	Defines which runners can be used in workflows	`self-hosted`, `ubuntu-latest`, etc.	Can restrict to specific runner groups or labels

Example: Setting workflow permissions

name: Workflow Permissions
on:
  push:
    branches: [ main ]
jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      actions: write

Note: Permissions can be set at the organization, repository, or job level. Organization-level settings act as defaults.

Warning: Setting actions: write allows workflows to modify organization settings and secrets.

7. Setting Allowed Actions

Setting	Description	Values	Notes
actions/allowed	Controls which actions are allowed to run in the organization	`all`, `github`, `enterprise`, `none`	Default is `github` for public repos, `enterprise` for private repos
actions/allowed-entities	Lists the entities that are allowed to run actions	Array of strings	Can include `github`, `enterprise`, or specific organization names

Example: Configure allowed actions in organization settings

name: Configure Allowed Actions
on:
  workflow_dispatch:

jobs:
  configure-allowed-actions:
    runs-on: ubuntu-latest
    steps:
      - name: Set allowed actions to enterprise and specific orgs
        uses: actions/github-script@v6
        with:
          script: |
            const allowedActions = [
              "github",
              "enterprise",
              "myorg"
            ];
            await github.rest.orgs.update({
              org: context.repo.owner,
              default_workflow_permissions: "read",
              allowed_actions: "enterprise",
              allowed_entities: allowedActions
            });

Note: The allowed_actions setting can be configured at the organization level and will apply to all repositories within that organization.

8. Using Private Actions

Property	Description	Example
uses	Specifies the action to use. For private actions, use the format `owner/repo@ref`.	`uses: myorg/private-repo@v1`
with	Passes input parameters to the action.	`with: token: ${{ secrets.GITHUB_TOKEN }}`

Example: Using a Private Action

name: Use Private Action
on:
  push:
    branches: [ main ]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Use Private Action
        uses: myorg/private-repo@v1
        with:
          token: ${{ secrets.GITHUB_TOKEN }}

Note: Private actions must be stored in a private repository within the same organization.

Warning: Ensure that the GITHUB_TOKEN has appropriate permissions to access private repositories.

9. Auditing Workflow Usage

Field	Description	Example
workflow_name	Name of the workflow being executed	`deploy-to-production.yml`
trigger	Event that triggered the workflow	`push`, `pull_request`
actor	User or app that initiated the workflow	`octocat`
repository	Repository where the workflow ran	`octocat/Hello-World`
run_id	Unique identifier for the workflow run	`123456789`
status	Outcome of the workflow run	`success`, `failure`
started_at	Timestamp when the workflow started	`2025-04-01T12:00:00Z`
completed_at	Timestamp when the workflow completed	`2025-04-01T12:05:00Z`

Example: Viewing Workflow Audit Logs

gh api repos/{owner}/{repo}/actions/runs/{run_id}/logs

Note: Audit logs are available via the GitHub API and can be used to track workflow execution history for compliance or debugging purposes.

10. Managing Billing

Feature	Description	Details
Usage Limits	GitHub Actions usage is subject to limits based on your plan	Free tier includes 2,000 minutes/month for public repos and 3,000 minutes/month for private repos
Billing Model	Pay-as-you-go for usage beyond limits	Each minute of workflow execution costs $0.003 for public repos and $0.005 for private repos
Organization Billing	Organizations can set up billing for all repositories under the organization	Access to detailed usage reports and cost allocation per repository or team
Cost Optimization	Strategies to reduce costs	Use caching, parallel jobs, and efficient workflows to minimize runtime

Example: Setting up Billing for Organization

gh org billing --set <billing-id>

Note: Billing is managed at the organization level, and can be configured via the GitHub UI or API.

11. Configuring Default Permissions

Permission	Description	Default Level	Notes
actions	Read and write access to workflow runs and artifacts	`read`	Required for most workflow operations
checks	Read and write access to checks	`read`	Used for status checks and annotations
contents	Read and write access to repository contents	`read`	Essential for workflows that modify files or push changes
deployments	Read and write access to deployments	`read`	Used for managing deployment environments
discussions	Read and write access to discussions	`read`	Used for managing repository discussions
issues	Read and write access to issues	`read`	Used for managing issue creation and updates
packages	Read and write access to packages	`read`	Used for publishing and managing packages
pages	Read and write access to Pages	`read`	Used for managing GitHub Pages deployments
pull-requests	Read and write access to pull requests	`read`	Used for managing PRs and reviews
repository-projects	Read and write access to repository projects	`read`	Used for managing project boards and cards
security-events	Read and write access to security events	`read`	Used for managing security alerts and findings
statuses	Read and write access to commit statuses	`read`	Used for managing status checks and commit statuses

Example: Setting Default Permissions in a Workflow

name: Example Workflow
on:
  push:
    branches:
      - main

permissions:
  contents: read
  issues: write
  pull-requests: write

jobs:
  example-job:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Run a script
        run: echo "Hello, world!"

12. Using Enterprise Features

Feature	Description	Availability	Notes
GitHub Enterprise Server	Self-hosted GitHub instance with enterprise-grade features	NEW GitHub Enterprise Server 3.12+	Includes advanced security, compliance, and customization options
GitHub Enterprise Cloud	Hosted GitHub with enterprise features and SLAs	Available to all GitHub Enterprise customers	Supports organization-level policies and custom branding
Custom Actions	Run custom actions on enterprise-managed runners	NEW GitHub Enterprise Server 3.10+	Enhanced security and control over action execution

Example: Using Custom Actions in Enterprise

name: Custom Enterprise Workflow
on:
  push:
    branches: [ main ]
jobs:
  build:
    runs-on: enterprise-runner
    steps:
      - name: Run Custom Action
        uses: myorg/custom-action@v1
        with:
          config: ${{ secrets.CUSTOM_CONFIG }}

Note: Enterprise features require appropriate licensing and may have different pricing structures than standard GitHub Actions.

Enterprise Features Overview

GitHub Enterprise Server provides self-hosted capabilities with enhanced security and compliance features.
GitHub Enterprise Cloud offers hosted enterprise-grade services with SLAs and organization-level controls.
Custom Actions allow enterprises to define and run their own actions with strict control over execution environments.