Events that trigger workflows

Note: The forge CI of git.pkgforge.dev is dormant. githome reads and validates workflow files, but an event starts no run, and a dispatch is refused with "CI is off on this deployment". This page is the reference for a deployment that turns the CI on.

The on: section of a workflow says which events start it. Githome supports the GitHub Actions events that matter for CI and automation: pushes, pull requests, merge queue groups, manual dispatch, schedules, other workflows' runs, published releases, external repository_dispatch events, reusable workflow calls, and the activity of the repository: issues and their comments, reviews and review comments, branches and tags created or deleted, labels, stars, commit statuses, deployments and check runs. This page lists each one with its activity types, filters, the GITHUB_SHA and GITHUB_REF its runs get, and its github.event payload.

#Supported events

Without types, a workflow runs for every activity type that Githome sends for its event (pull_request, pull_request_target and merge_group have their own defaults, given in their sections).

#Other GitHub events

The other GitHub event names (discussion, discussion_comment, fork, gollum, milestone, page_build, project, project_card, project_column, public, registry_package and branch_protection_rule) are accepted in on: without an error or warning, so workflows that list them still parse, but Githome never starts a run for them. A name that isn't a GitHub event at all gives the warning unknown event '<name>' in githome workflow validate.

#Writing on

on: push                          # one event, no configuration

on: [push, pull_request]          # several events, no configuration

on:                               # events with configuration
  push:
    branches: [main]
    tags: ["v*"]
  pull_request:
    types: [opened, synchronize, reopened, closed]
    paths: ["src/**"]
  workflow_dispatch:

An event's configuration must be a mapping (on.<event> must be a mapping), except schedule, which is a list. Each workflow file whose on: matches an event gets one run for it.

#Filter patterns

Branch, tag and path filters use GitHub's filter pattern syntax:

Patterns match the whole name: a branch name without refs/heads/, a tag name without refs/tags/, or a file path relative to the repository root. Quote patterns that start with *, ! or [ in YAML.

A list is read in order, and the last pattern that matches decides: a value is included when it matches a positive pattern and no later ! pattern excludes it. A ! pattern can only exclude what an earlier pattern included, so a list of only ! patterns matches nothing.

on:
  push:
    branches:
      - "releases/**"
      - "!releases/**-alpha"

This runs for releases/10 and releases/beta/mona, but not releases/10-alpha.

#Include and ignore filters

• branches runs the workflow only for matching branches; branches-ignore runs it for every branch except matching ones. The same goes for tags and tags-ignore, and paths and paths-ignore.
• You can't use a filter and its -ignore form for the same event. The file fails with 'branches' and 'branches-ignore' cannot be used together for the same event (or the same message for tags or paths). Use ! patterns in the positive form instead.

#Path filters

• With paths, the workflow runs when at least one changed file matches the list.
• With paths-ignore, the workflow runs unless every changed file matches the list.
• For a push, the changed files are the difference between the commit before the push and the pushed commit. When the push creates a new branch, or the previous commit isn't known, Githome can't compute the change and path filters pass. (GitHub compares a new branch with the default branch instead.)
• For a pull request, the changed files are those the pull request changes, compared with the merge base of the head and the base branch. When a merged pull request is closed, path filters pass.
• Path filters are never evaluated for tag pushes.
• When branch or tag filters and path filters are both set, both must pass.

#push

Runs when you push to a branch or tag, including pushes that create a branch or tag, force pushes, pushes by agents, and merges made through the web UI, CLI, API or merge queue. Deleting a branch or tag doesn't start push runs; it sends delete.

on:
  push:
    branches: [main, "release/**"]
    tags: ["v*.*.*"]
    paths-ignore: ["docs/**", "**.md"]

How branches and tags combine, as on GitHub:

The workflow file is read from the pushed commit, so a push that changes a workflow runs the new version.

When a merge queue builds a merge group, it pushes a branch named gh-readonly-queue/<base>/pr-<n>-<head sha>, and push workflows run on it as on GitHub. Add branches-ignore: ["gh-readonly-queue/**"] (or list only the branches you want) to avoid running twice.

Payload (github.event):

#pull_request

Runs for activity on a pull request, using the workflow and code of the pull request's test merge commit: the head branch merged into the current base branch, as on GitHub.

on:
  pull_request:
    types: [opened, synchronize, reopened]
    branches: [main]
    paths: ["src/**", "package.json"]

Without types, the workflow runs for opened, synchronize and reopened, as on GitHub. GitHub's other types (labeled, assigned, review_requested, locked and so on) are accepted in types but never fire on Githome.

A common use is to skip expensive jobs while a pull request is a draft and run them once it's ready:

on:
  pull_request:
    types: [opened, synchronize, reopened, ready_for_review]
jobs:
  e2e:
    if: ${{ !github.event.pull_request.draft }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm run e2e

For edited, the payload has no changes object with the old title or body (GitHub sends one).

branches and branches-ignore filter on the pull request's base branch.

• The run checks out and runs refs/pull/<n>/merge. You can fetch that ref and refs/pull/<n>/head with git, but not push to them.
• While a pull request conflicts with its base, there is no test merge commit and its pull_request workflows don't run. pull_request_target workflows still do.
• For closed on a merged pull request, the run uses the merge commit instead.
• The run's checks are reported on the pull request's head commit, so they appear on the pull request.
• Every pull request comes from a branch of the same repository, so pull_request runs get the repository's secrets, like push runs.

Payload (github.event):

#pull_request_target

Same activity types, filters and payload as pull_request, but the run uses the base branch's own workflow file and code: the base branch's current commit. A pull request therefore can't change what runs with the repository's secrets. Check out the pull request's code (for example with ref: ${{ github.event.pull_request.head.sha }}) only if you trust it.

on:
  pull_request_target:
    types: [opened, reopened]
jobs:
  welcome:
    runs-on: ubuntu-latest
    steps:
      - run: echo "Thanks for pull request #${{ github.event.number }}, ${{ github.event.pull_request.user.login }}"

Unlike pull_request, it also runs while the pull request conflicts with its base. Checks are reported on the pull request's head commit.

#merge_group

Runs when the merge queue builds a merge group for a pull request: a commit holding the base branch, every pull request ahead in the queue, and this pull request's changes. The queue merges the pull request once the group's required checks pass. See Merge queue.

on:
  pull_request:
  merge_group:
    types: [checks_requested]
    branches: [main]

• The only activity type is checks_requested, which is also the default.
• branches and branches-ignore filter on the queue's base branch.
• The queue reads the required checks from the merge group commit, so the workflows that produce them must run on it: list merge_group next to pull_request. (A push workflow without branch filters also runs there.) If a required check never reports, the pull request leaves the queue when the queue's check timeout expires.
• push workflows also run on the merge group branch; see push.
• A merge group commit with an invalid workflow file gets an Invalid workflow file run, like a push.

Payload (github.event):

The run's title is Merge group for #<n>: <pull request title>.

#workflow_dispatch

Lets people and agents with write access start the workflow on demand, on a branch or tag they choose, with typed inputs. How to start a run from the web UI, the CLI, the API and MCP is in Actions overview.

on:
  workflow_dispatch:
    inputs:
      environment:
        description: Target environment
        type: choice
        options: [staging, production]
        default: staging
      version:
        description: Version to deploy
        required: true
      replicas:
        type: number
        default: 2
      dry-run:
        type: boolean
        default: false
      target:
        type: environment

Each input can have:

Values are converted by type: boolean inputs become true when the value is true or "true" and false otherwise; number inputs become numbers; string, choice and environment inputs stay as given. Values for inputs the workflow doesn't declare are dropped. An environment input is a plain text field in the Run workflow form, and its value isn't checked against the repository's environments.

Read inputs with the inputs context (${{ inputs.version }}). github.event.inputs holds the same values with the same types; on GitHub, github.event.inputs values are always strings.

The workflow must exist and have a workflow_dispatch trigger at the chosen ref. A ref given without refs/ is a branch if a branch with that name exists, and a tag otherwise.

Payload (github.event): inputs, ref (the full ref), workflow (the workflow file's path), repository and sender.

Each accepted dispatch also sends a workflow_dispatch webhook event with the same ref, workflow and inputs, to webhooks subscribed to it.

#schedule

Runs the workflow on a schedule, in UTC.

on:
  schedule:
    - cron: "30 5 * * 1-5"    # 05:30 UTC, Monday to Friday
    - cron: "0 */6 * * *"     # every 6 hours

schedule is a list of entries with a cron string. Each cron has 5 fields:

Each field accepts *, a value, a range (1-5), a list (1,15,30) and a step (*/15, 0-30/10, or 5/15 meaning from 5 to the end every 15). Names are case-insensitive. As in standard cron, when both day of month and day of week are restricted, a day matches if either one matches.

How schedules run:

• Granularity is 5 minutes. Githome checks schedules every 5 minutes and starts every schedule that was due at any minute since the last check. A schedule for 2 * * * * starts a few minutes after :02, and one for * * * * * runs once per check, not every minute. GitHub's minimum interval is also 5 minutes. A check that comes late is caught up by the next one (up to an hour back), and a schedule starts once however many of its minutes it covers.
• Only the default branch counts. Schedules are read from the workflow files on the default branch, and refreshed on every push to it. A schedule in a workflow on another branch does nothing.
• Each run uses the workflow file on the default branch at that moment, and only if it still has that exact cron string.
• Schedules of archived repositories don't run.
• The run's actor is githome-scheduler. Notifications for scheduled runs go to the repository's watchers.

Invalid crons fail the file with Invalid cron: <detail>, for example Invalid cron: Cron '0 3 * *' must have exactly 5 fields (minute hour day-of-month month day-of-week), minute value 60 out of range 0-59 in cron '<cron>' or Invalid step '0' in minute field of cron '<cron>'. schedule must be a list (on.schedule must be a list of { cron: '...' } entries) and each entry needs a cron string (on.schedule entries must have a 'cron' string).

Payload (github.event): schedule (the cron string) and repository.

#workflow_run

Runs after a run of another workflow is requested or completes. Use it to post-process another workflow's results with access to secrets, or to chain workflows.

name: Report
on:
  workflow_run:
    workflows: [CI]
    types: [completed]
    branches: [main]
jobs:
  report:
    if: ${{ github.event.workflow_run.conclusion == 'failure' }}
    runs-on: ubuntu-latest
    steps:
      - run: echo "CI failed on ${{ github.event.workflow_run.head_branch }}: ${{ github.event.workflow_run.html_url }}"

• workflows is required: a list of workflow names (each workflow's name, or its path when it has none). A workflow_run trigger without workflows never fires.
• types can be requested (when the other run is created, including re-runs) and completed. Without types, both fire. GitHub's in_progress type never fires on Githome.
• branches and branches-ignore filter on the other run's head branch: the pushed branch, or the pull request's head branch for pull request runs.
• Like on GitHub, the triggered workflow is read from the default branch and runs there, whatever branch the other run was on.
• Chains stop after three levels: if A triggers B, B triggers C and C triggers D, D's runs don't trigger anything.
• If the run it follows came from an agent (for example CI on a branch an agent pushed), the workflow_run run counts as agent code too, although it runs on the default branch: its GITHUB_TOKEN acts as an agent and environment secrets follow the agent rules. A follower acts on what the other run produced (artifacts, outputs), so it can't be used to carry agent-written results past the agent guardrails. See GITHUB_TOKEN permissions.

Payload (github.event):

#release

Runs when a release changes: when it's published, unpublished, edited or deleted. Use it to build and attach binaries, publish packages or deploy when you publish a release. Releases are managed on the repository's Releases page (https://git.pkgforge.dev/acme/website/releases), with POST /api/v3/repos/{owner}/{repo}/releases and PATCH /api/v3/repos/{owner}/{repo}/releases/{release_id}, or with the create_release and update_release MCP tools. All of them need write access. See Releases.

name: Release
on:
  release:
    types: [published]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: make dist VERSION="${{ github.event.release.tag_name }}"

Each change sends one or more activity types, and a workflow with on: release and no types runs once for each of them. Creating a published release sends three (created, published and released), so you get three runs. Set types to the ones you need; types: [published] is the usual choice.

How a release run is set up:

• The run uses the commit the release's tag points to (the commit, for an annotated tag), and the workflow file at that commit. If the tag doesn't exist (for example it was deleted after the release was published), no run starts.
• Publishing a release whose tag doesn't exist yet creates the tag at target_commitish (the default branch when it's not set). Creating the tag is a push of that tag, so push workflows that match the tag run too, as on GitHub. Use either on: push: tags or on: release for the same job, not both.
• The run's title is the release's name, or its tag name when the release has no name.
• The run's actor is whoever made the change. Its checks are reported on the tagged commit.
• types is the only filter. branches, tags and paths aren't applied to release; check github.event.release.tag_name or github.ref_name in an if: instead.
• Invalid workflow files are skipped without an Invalid workflow file run.

Payload (github.event):

Uploading an asset needs contents: write. Give the job that permission and use its GITHUB_TOKEN, or use a personal or agent token stored as a secret (see GITHUB_TOKEN permissions):

on:
  release:
    types: [published]
jobs:
  upload:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: tar czf dist.tar.gz src
      - name: Attach dist.tar.gz to the release
        env:
          TOKEN: ${{ secrets.RELEASE_TOKEN }}
          UPLOAD_URL: ${{ github.event.release.upload_url }}
        run: |
          curl -fsS -X POST "${UPLOAD_URL%\{*}?name=dist.tar.gz" \
            -H "Authorization: Bearer $TOKEN" \
            -H "Content-Type: application/gzip" \
            --data-binary @dist.tar.gz

#repository_dispatch

Runs when someone calls the dispatches endpoint of the repository with an event type. Use it to start workflows from outside Githome: another system's CI, a deployment tool, a chat bot or an agent.

on:
  repository_dispatch:
    types: [deploy, rollback]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: ./deploy.sh "${{ github.event.action }}" "${{ github.event.client_payload.version }}"

• types lists the event_type values that start the workflow. Without types, every event_type does.
• Like on GitHub, the workflow is read from the default branch's latest commit and runs there.
• The run's title is the event_type, and its actor is the account whose token sent the request.
• Invalid workflow files are skipped without an Invalid workflow file run.

#Send a repository_dispatch event

You need write access to the repository, with a token that has the write scope (see Tokens). People and agents can both send events.

curl -X POST https://git.pkgforge.dev/api/v3/repos/acme/website/dispatches \
  -H "Authorization: Bearer ghome_..." \
  -H "Content-Type: application/json" \
  -d '{"event_type": "deploy", "client_payload": {"version": "1.4.2", "environment": "staging"}}'

The answer is 204 No Content, as on GitHub, also when no workflow listens for the event type. The request doesn't return the runs it started; find them with GET /api/v3/repos/acme/website/actions/runs?event=repository_dispatch or githome run list -R acme/website -e repository_dispatch. Webhooks subscribed to repository_dispatch also get the event.

Payload (github.event):

#workflow_call

Makes the workflow reusable: other workflows call it from a job with uses:. It never starts a run on its own.

on:
  workflow_call:
    inputs:
      node-version:
        type: string
        default: "22"
    secrets:
      npm-token:
        required: true
    outputs:
      version:
        value: ${{ jobs.build.outputs.version }}

inputs take type (required: string, boolean or number), description, required and default. secrets take description and required. outputs each need a value. Runs of a called workflow use the caller's event, ref, commit and github context. The full reference is in Reusable workflows.

#Repository activity events

The events of this section come from what people, agents and apps do in the repository, through the web UI, the CLI, the API or MCP.

• Most of them run the workflow file of the default branch's latest commit, on the default branch. create, deployment, deployment_status, pull_request_review and pull_request_review_comment run where their table says.
• Without types, a workflow runs for every activity type that Githome sends for the event. types: [opened] keeps out the others.
• An invalid workflow file is skipped without an Invalid workflow file run.
• The run's actor is whoever made the change. The payload has the fields listed in each section: issue, comment, review, pull_request, label and milestone as the REST API returns them, and repository, sender and (for an organization's repository) organization.
• What a job does with its own GITHUB_TOKEN starts no run (see Runs started from inside a workflow). Neither does what Githome writes by itself: the comment of auto-merge when it turns off, the comment of the merge queue when it removes a pull request, the check of agent review, and the branches of a merge group. A job's write can cause each of them, and GitHub writes no such comment.
• While the CI of the deployment is off, these events start nothing and read nothing: no workflow file, no payload and no test merge.
• An event that no workflow of its commit listens to builds no payload. Githome parses the workflow files of a commit once for a burst of events on it.

Some changes send many events, as on GitHub, and each listening workflow runs once for each of them, on the repository owner's minutes: adding many labels to an issue sends one labeled for each label (and one label created for each new name), a review with many comments sends one pull_request_review and one pull_request_review_comment for each comment, and starring a repository again after removing the star sends watch again. Filter with types and if: where a workflow only needs some of them.

#issues

on:
  issues:
    types: [opened, labeled]
jobs:
  triage:
    runs-on: ubuntu-latest
    steps:
      - run: echo "Issue #${{ github.event.issue.number }}: ${{ github.event.issue.title }}"

A pull request sends pull_request instead, as on GitHub. GitHub's other types (deleted, transferred, pinned, unpinned, typed, untyped) are accepted in types but never fire on Githome, which has none of these operations. An issue opened with labels or assignees sends opened only, not a labeled or assigned for each.

Payload: action, issue (with number, title, body, state, user, labels, assignees, locked and the URLs of the REST API), and changes, assignee, label or milestone for the types above.

#issue_comment

Runs when a comment on an issue, or on the conversation of a pull request, is created, edited or deleted. A comment on a pull request has github.event.issue.pull_request, as on GitHub; check it to tell the two apart.

Payload: action, issue, comment (id, body, user, created_at, updated_at, html_url and url), and for edited, changes.body.from.

#pull_request_review

Runs when a review of a pull request is submitted (an approval, a request for changes or a comment, and a pending review once it is submitted) or dismissed. GitHub's edited type never fires on Githome.

Like pull_request, the run uses the workflow and code of the pull request's test merge commit, and its checks are reported on the pull request's head commit. While the pull request conflicts with its base, no run starts. A review of a pull request from a fork runs as that fork's pull_request runs do: a read-only GITHUB_TOKEN and no secrets.

Payload: action, review (id, body, state in lower case, such as approved, user, commit_id, submitted_at) and pull_request.

#pull_request_review_comment

Runs when a comment on the diff of a pull request is created (each comment of a submitted review, and a single comment or reply), edited or deleted. A single comment or reply is a review of one comment, so it also sends pull_request_review submitted. The comments of a pending review send nothing until the review is submitted. It runs where pull_request_review runs, and a review and its comments share one test merge commit.

Payload: action, comment (id, body, path, line, side, commit_id, user, pull_request_review_id), pull_request, and for edited, changes.body.from.

#create

Runs when a branch or tag is created: by a push, POST /repos/{owner}/{repo}/git/refs, a new branch from the web UI, or a published release whose tag didn't exist. A push that creates more than three tags sends no create event for them. The branch of a merge group (gh-readonly-queue/...) sends none: the merge queue creates it.

Payload: ref (the short name), ref_type (branch or tag), master_branch, description (null) and pusher_type (user).

#delete

Runs when a branch or tag is deleted, also when a merged pull request's branch is deleted. A push that deletes more than three tags sends no delete event for them, and the merge queue's deletion of a merge group's branch sends none.

Payload: ref (the short name), ref_type and pusher_type.

#label

Runs when a label of the repository is created (also when adding a label that doesn't exist to an issue creates it), edited (changes has the old name, color or description) or deleted. Renaming or deleting a label sends no event for each issue that has it.

Payload: action, label (id, name, color, description, url) and, for edited, changes.

#watch

Runs when someone stars the repository (PUT /user/starred/{owner}/{repo}). The only type is started. A second star by the same person, and a star of an archived repository, start nothing.

Payload: action (started).

#status

Runs when a commit status is created (POST /repos/{owner}/{repo}/statuses/{sha}).

Payload: id, sha, name, state, context, description, target_url, commit.sha, created_at and updated_at.

#deployment

Runs when a deployment is created with POST /repos/{owner}/{repo}/deployments. The deployments that a job with environment: records start no run, as on GitHub, so a workflow can't trigger itself through them.

Payload: action (created) and deployment (id, sha, ref, task, environment, description, payload, created_at).

#deployment_status

Runs when a deployment status is created for a deployment of the API. As on GitHub, a status inactive starts no run, and neither do the statuses of a job's own deployment.

Payload: action (created), deployment_status (id, state, description, environment, environment_url, log_url, created_at) and deployment (id, sha, ref, task, environment).

#check_run

Runs when a check run that an app or a person reports over the API is created, and when an update completed it. GitHub's rerequested and requested_action types never fire on Githome. The check runs of Githome Actions jobs and the check of agent review send no event, by any door.

Payload: action and check_run (id, name, head_sha, status, conclusion, started_at, completed_at, output, app, check_suite.id).

#check_suite

Runs when the last unfinished check run of an app on a commit completes, so the app's suite on that commit is completed. Githome sends completed only: GitHub's requested and rerequested types never fire on Githome. The suites of Githome Actions runs and of agent review send no event.

Payload: action (completed) and check_suite (id, head_sha, status, conclusion, app, latest_check_runs_count).

#GITHUB_SHA and GITHUB_REF by event

A re-run keeps the original run's commit, ref, event and payload.

#The repository object

Every payload has a repository field with GitHub's full repository object, the same one the REST API returns for GET /repos/{owner}/{repo}. The fields workflows read most:

For a repository owned by an organization, payloads also have an organization field with login, id (a number), node_id, url, repos_url, avatar_url and description.

The payload is also written to the file at GITHUB_EVENT_PATH for tools that read it from disk, such as @actions/github's context.payload in actions/github-script.

#The sender object

sender is the account that caused the event, as a GitHub user object:

#Runs started from inside a workflow

As on GitHub, an event caused by a job's own GITHUB_TOKEN doesn't start new workflow runs, so workflows can't trigger themselves in a loop with it. A push, a pull request, a release, an issue, a comment, a review, a label, a milestone, a commit status, a deployment or a check run made with a job token starts nothing, and neither does what Githome writes by itself because of it (auto-merge turned off by the job's push, a pull request that the merge queue removes, agent review's check). The two exceptions, as on GitHub, are workflow_dispatch (a job with permissions: actions: write can start another workflow with POST /repos/{owner}/{repo}/actions/workflows/{workflow_id}/dispatches) and repository_dispatch (a job with contents: write can send POST /repos/{owner}/{repo}/dispatches).

Events caused by a personal or agent token stored as a secret, or by an app's installation token, are treated like any other event from that account or app and do start workflows: a push starts push workflows, a published release starts release workflows, a comment starts issue_comment workflows, and a dispatch starts repository_dispatch workflows. Two workflows that use such tokens can start each other without end. As on GitHub, nothing but the workflows themselves stops that: Githome only caps the runs of a repository that haven't finished (500 at a time, then new events start nothing until some finish) and the requests of each token (see Limits).

- name: Ask the deploy workflow to run
  env:
    TOKEN: ${{ secrets.DISPATCH_TOKEN }}
  run: |
    curl -fsS -X POST "${{ github.api_url }}/repos/${{ github.repository }}/dispatches" \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -d '{"event_type": "deploy", "client_payload": {"sha": "${{ github.sha }}"}}'

Guard against loops, for example with paths-ignore, types, or an if: that checks github.actor or the commit message.

#Differences from GitHub

• Only the events in Supported events start runs. Other GitHub event names parse but never fire.
• pull_request and pull_request_target fire for opened, synchronize, reopened, closed, edited, ready_for_review and converted_to_draft only, and the edited payload has no changes object.
• workflow_run fires for requested and completed, not in_progress, and requires workflows.
• release workflows get no branches, tags or paths filtering, and a published release whose tag doesn't exist any more starts no runs.
• issues, pull_request_review, check_run and check_suite never send the types of an operation Githome doesn't have, listed in their sections, and an issue opened with labels or assignees sends opened only.
• The deployments and statuses that a job with environment: records go to webhooks but start no run, as on GitHub, where Actions records them.
• push payloads list only the pushed commit in commits.
• Path filters pass when a push creates a branch.
• github.event.inputs keeps input types.
• schedule is checked every 5 minutes; a schedule runs within about 5 minutes after it is due.