Organizations Templated workflow

In this guide, you’ll discover how to define and consume organization-wide starter workflows for GitHub Actions. By centralizing your CI/CD logic in a special .github repository, teams can pick prebuilt workflow templates across all repos—boosting consistency and cutting down duplication.

1. Define a Starter Workflow Template

To publish a reusable workflow:

1. Create a public repository named .github at the root of your organization.
2. Inside .github, add a folder called workflow-templates.
3. Add a workflow YAML file (for example, org-ci-starter.yml).
4. Add a matching metadata file named org-ci-starter.properties.json.

Table: Starter Template Files

Example workflow (.github/workflow-templates/org-ci-starter.yml):

name: Octo Organization CI
on:
  push:
    branches: [ $default-branch ]
  pull_request:
    branches: [ $default-branch ]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

Example metadata (.github/workflow-templates/org-ci-starter.properties.json):

{
  "name": "Octo Organization Workflow",
  "description": "CI starter workflow for Go projects.",
  "iconName": "Example-icon",
  "categories": ["Go"],
  "filePatterns": ["package.json$", "Dockerfile", "\\.md$"]
}

2. Create Your GitHub Organization

If you don’t already have an organization, set one up:

1. Click your profile photo → Your organizations.
2. Select New organization, choose the Free plan.
3. Enter an organization name and contact email.
4. Complete account verification and accept the terms.
5. Skip adding members initially—you can invite collaborators later.

Once your organization is ready, you’ll land on its settings dashboard:

3. Set Up the .github Repository

Within your organization:

1. Click New repository → Enter .github as the name.
2. Set Visibility to Public.
3. Initialize with a README (optional) and click Create repository.

Next, create the workflow-templates/ folder in the .github repo—either via the web editor or locally:

Add your template files, for example:

After committing, the repo structure should resemble:

4. Example: Node.js CI Starter Workflow

Create .github/workflow-templates/nodejs-ci-starter-workflow.yml:

name: KodeKloud Demo Organization NodeJS CI
on:
  push:
    branches: [ $default-branch ]
  pull_request:
    branches: [ $default-branch ]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Repository
        uses: actions/checkout@v4
      - name: Setup Node.js (20.x)
        uses: actions/setup-node@v4
        with:
          node-version: '20.x'
      - name: Install Dependencies
        run: npm install
      - name: Run Tests
        run: npm test --if-present
      - name: Generate Coverage
        run: npm run coverage --if-present

Add metadata at .github/workflow-templates/nodejs-ci-starter-workflow.properties.json:

{
  "name": "KodeKloud Demo Organization NodeJS CI",
  "description": "Starter workflow for Node.js projects.",
  "iconName": "kode-kloud-icon",
  "categories": ["NPM Config"]
}

You may also upload an SVG icon (e.g., kode-kloud-icon.svg) to the same folder.

5. Consume the Starter Workflow

In any new or existing repo under your org:

1. Click New repository, initialize with a README if desired.
2. Navigate to the Actions tab.

Below GitHub’s built-in suggestions, you’ll see your organization’s starter templates:

You can also filter by deployment, security, CI, and more:

Click Configure on your Node.js CI starter. GitHub will generate the YAML and replace $default-branch (e.g., main):

name: KodeKloud Demo Organization NodeJS CI
on:
  push:
    branches: ["main"]
  pull_request:
    branches: ["main"]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Repository
        uses: actions/checkout@v4
      - name: Setup Node.js (20.x)
        uses: actions/setup-node@v4
        with:
          node-version: '20.x'
      - name: Install Dependencies
        run: npm install
      - name: Run Tests
        run: npm test --if-present
      - name: Generate Coverage
        run: npm run coverage --if-present

Customize steps or add new jobs, then commit to kick off the workflow.

6. Configure Runners for Organization Repos

If your workflow remains queued, verify runner access:

1. In the repo: Settings > Actions > Runners—you may see none configured.

2. At the org level: Settings > Actions > Runners. The default runner group might exclude public repos.

3. Edit the default group to allow all repositories (including public).

Once configured, GitHub-hosted runners will pick up jobs:

Links and References

• GitHub Actions Starter Workflows
• Creating a GitHub Organization
• Managing Self-hosted Runners