> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Organizations Templated workflow
> This guide explains how to create and use organization-wide starter workflows for GitHub Actions to enhance consistency and reduce duplication.
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`.
The metadata JSON controls how your template appears in the workflow picker.
* `name` and `description` define the display text.
* `iconName` lets you specify an optional SVG icon.
* `categories` and `filePatterns` help users find the right template.
Table: Starter Template Files
| File Path | Purpose | Example Filename |
| ------------------------------------------------------- | ---------------------------- | -------------------------------- |
| `.github/workflow-templates/{template}.yml` | Workflow definition | `org-ci-starter.yml` |
| `.github/workflow-templates/{template}.properties.json` | Display metadata | `org-ci-starter.properties.json` |
| (Optional) `.github/workflow-templates/{icon}.svg` | Custom icon for the template | `kode-kloud-icon.svg` |
Example workflow (`.github/workflow-templates/org-ci-starter.yml`):
```yaml theme={null}
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`):
```json theme={null}
{
"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`:
```yaml theme={null}
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`:
```json theme={null}
{
"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`):
```yaml theme={null}
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:
If no runners are permitted, workflows will remain queued indefinitely. Always verify your runner group settings after creating or migrating repositories.
***
## Links and References
* [GitHub Actions Starter Workflows](https://docs.github.com/actions/learn-github-actions/starter-workflows)
* [Creating a GitHub Organization](https://docs.github.com/organizations)
* [Managing Self-hosted Runners](https://docs.github.com/actions/hosting-your-own-runners)