---
title: Workflow setup
description: Enable the Copilot action for issue events and what runs when.
---

# Workflow setup

To run Copilot on **issue** events, add a workflow that uses the `issues` trigger and passes the required inputs (at least `token`). This page describes the **events** to use and **what the action does** on each run.

## Trigger events

Use the `issues` trigger with the types you need. Common setup:

```yaml
on:
  issues:
    types: [opened, reopened, edited, labeled, unlabeled, assigned, unassigned]
```

| Event type | When it runs | Typical use |
|------------|--------------|-------------|
| `opened` | A new issue is created | Link to projects, assign members, apply initial behavior (e.g. if branch-management-always, create branch). |
| `reopened` | A closed issue is reopened | Re-apply linking/assignees; branch creation may run again depending on labels. |
| `edited` | Issue title or body is edited | Update project/title/linking if needed. |
| `labeled` | A label is added to the issue | **Branch creation** when the launcher label (e.g. `branched`) is added, or when type is hotfix/release; deploy trigger when `deploy` is added. |
| `unlabeled` | A label is removed | Update state (e.g. branch already exists; deploy label removed). |
| `assigned` / `unassigned` | Assignees change | Sync with project/assignees if your flow depends on it. |

For **branch creation**, the most important event is usually **`labeled`**: when the user adds the **branch launcher label** (default: `branched`) or when the issue has a hotfix/release label and the creator is a member, the action creates the branch. See [Branch management](/issues/branch-management).

## Minimal workflow

Create a file under `.github/workflows/` (e.g. `copilot_issue.yml`):

```yaml
name: Copilot - Issue

on:
  issues:
    types: [opened, reopened, edited, labeled, unlabeled, assigned, unassigned]

jobs:
  copilot-issues:
    name: Copilot - Issue
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Repository
        uses: actions/checkout@v4

      - uses: vypdev/copilot@v3
        with:
          token: ${{ secrets.PAT }}
          project-ids: ${{ vars.PROJECT_IDS }}
```

- **`token`** is required (use a fine-grained PAT with repo and project permissions; see [Authentication](/authentication)).
- **`project-ids`** is optional but needed if you want issues (and PRs) linked to GitHub Project boards.

Add other inputs as needed: `branch-management-launcher-label`, `desired-assignees-count`, `main-branch`, `development-branch`, etc. See [Configuration](/issues/configuration) and [Examples](/issues/examples).

## What runs when

1. **Admission on every trigger** (with valid `token`): The action first compares the **event actor** with the **token owner**. If they are the same, the normal pipeline completes successfully before queueing or loading issue context (see [Troubleshooting → Action skips issue/PR/push pipelines](/security-operations/operations/troubleshooting#action-skips-issueprpush-pipelines)); use a **bot account** for the PAT if you want full behavior when you act as a user. Valid explicit single actions still run.

   Set the optional Repository Variable `COPILOT_BOT_LOGIN` to the PAT bot's login to apply the same generic check at job admission. Event workflows triggered by that actor then consume no runner at all. If the variable is absent, the in-Action authenticated check remains fail-safe. Manual single-action workflows are intentionally separate and are not gated this way.

2. **Project linking:** If `project-ids` is set and the token has access, the issue is linked to those projects and moved to the configured column (e.g. "Todo" or "In Progress").

3. **Assignees:** If `desired-assignees-count` is set, the action assigns up to that many members (issue creator first if they belong to the org/repo, then additional members). See [Assignees and projects](/issues/assignees-and-projects).

4. **Branch creation:** When the issue has a **branch type** label (feature, bugfix, docs, chore, hotfix, release) and either the **launcher label** (e.g. `branched`) is present or `branch-management-always: true`, the action creates the branch (with hotfix/release restrictions for non-members). See [Branch management](/issues/branch-management).

5. **Deploy trigger:** When the `deploy` label is added to an issue that has a release or hotfix type, the action **dispatches** the workflow named in `release-workflow` or `hotfix-workflow` (e.g. `release_workflow.yml`, `hotfix_workflow.yml`). Filenames must match exactly.

## Scheduled inactivity cleanup

To close issues that remain waiting for a maintainer or issue author, add
`setup/workflows/copilot_close_inactive_issues.yml` to the destination repository
or enable the `inactiveIssueClosure` feature in `copilot setup`. The template runs
every six hours and can also be started manually:

```yaml
on:
  schedule:
    - cron: '0 */6 * * *'
  workflow_dispatch:
    inputs:
      inactivity_threshold_hours:
        description: Hours without activity before closing a waiting issue
        required: false
        default: '168'
        type: string
```

The workflow invokes `single-action: close_inactive_issues_action` and needs the
write-capable `PAT` Secret. The default threshold is 168 hours (7 days); set
`INACTIVITY_THRESHOLD_HOURS` as a Repository Variable or pass
`inactivity-threshold-hours` to override it. The action uses the existing
`state:awaiting-maintainer`, `state:awaiting-issue-author`, and
`state:ai-processing` labels, which can be customized through the normal label
inputs.

## Next steps

- **[Assignees and projects](/issues/assignees-and-projects)** — Member assignment and project linking.
- **[Branch management](/issues/branch-management)** — When and how branches are created.
- **[Examples](/issues/examples)** — Full workflow YAML examples.