Schedule regularly occurring meetings via GitHub Issue

Schedule meetings via a GitHub Action. Creates issues based on a schedule and template.

This repository is managed by the Package Maintenance Working Group, see Governance.

Usage

name: Schedule team meetings
on:
  schedule:
    - cron: '0 0 * * * *'  # Run daily at midnight UTC
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: pkgjs/meet@v1
      with:
        token: ${{ secrets.GITHUB_TOKEN }}
        schedules: 2020-04-02T17:00:00[America/Chicago]/P1D  # Every 1 day from 2020-04-02 at 5PM Chicago time
        createWithin: P2D  # Create issue 2 days before the scheduled meeting

Github Action Inputs

The meeting schedule, issue, etc can be configured with inputs to this action.

• token: (required) The token from the action for calling to the GitHub API.
• schedules: (required) The meeting schedules. Supports timezone identifiers (e.g., 2020-04-02T17:00:00[America/Chicago]/P7D) or UTC (e.g., 2020-04-02T17:00:00Z/P7D). Offset usage is not allowed. Default: ${now/P7D} seven days from now
• createWithin: (required) The ISO-8601 duration for how soon before the meeting to create the issue. Default P7D
• meetingLabels: The labels to apply to issues generated by this GitHub Action for meetings. Default: meeting
• agendaLabel: Label to pull the agenda from. Default: meeting-agenda
• issueTitle: Template string for issue title. Default: Meeting <%= date.toZonedDateTimeISO('UTC').toPlainDate().toString() %>
• issueTemplate: The name of the issue template found in .github/ISSUE_TEMPLATE. Default: meeting.md

Schedule format

The action supports RFC 3339 timezone formats with two schedule options:

Timezone identifiers (recommended)

Use timezone identifiers for automatic DST handling:

schedules: |
  2020-04-02T17:00:00[America/Chicago]/P7D
  2020-06-15T14:00:00[Europe/London]/P14D

This ensures meetings maintain the same wall-clock time throughout the year, automatically adjusting for daylight saving time transitions.

UTC time

Use UTC for absolute time scheduling:

schedules: |
  2020-04-02T17:00:00Z/P7D

Invalid formats

The following formats are not supported and will cause errors:

• 2020-04-02T17:00:00-06:00/P7D (offset usage)
• 2020-04-02T17:00:00-06:00[America/Chicago]/P7D (offset + timezone)
• 2020-04-02T17:00:00/P7D (no timezone or UTC specified)

Default Issue Template

The default issue template can be seen in the ISSUE_TEMPLATES directory, as meeting.md. Additionally, you can find example issues of the latest version via the closed issues that are the result of CI tests.

Our default template is based off of the Node.js project's practices around meetings, but changes and enhancements are welcome.

Custom Issue Templates

If you don't want to use the default issue template, you can use a custom issue template by passing in the file name of it (presuming it lives in ISSUE_TEMPLATES).

You can use both our shorthand and JavaScript in your meeting templates.

Template Data and Automatic Replacements

Autoreplacing Shorthand in Custom Meeting Templates

We provide some shorthand that you can use in your meeting templates. We'll automatically replace the shorthand with the relevant dynamic information.

If you'd like to see more shorthand available, we absolutely welcome PRs.

• <!-- title -->: The issue's title.
• <!-- agenda label -->: The label for agenda items to be pulled from that you've defined in the Action's YAML configuration.
• <!-- invitees -->: The list of invitees you've defined in the Action's YAML configuration.
• <!-- observers -->: The list of observers you've defined in the Action's YAML configuration.
• <!-- meeting link -->: The meeting video call link

## Title
<!-- title -->

## Agenda Items
Extracted from issues labelled with <!-- agenda label -->.

## Participants
- Invitees: <!-- invitees -->
- Observers: <!-- observers -->

JavaScript in Your Custom Meeting Templates

You can include custom JavaScript in your custom meeting templates. We use ejs, so anything within an ejs tag will be parsed as JavaScript.

When using EJS templates for your meeting issues, the following data properties are available:

EJS Template Data

• date: Temporal.Instant - The date of the meeting, formatted using Temporal for timezone conversions and Intl.DateTimeFormat for locale-aware formatting.
• agendaIssues: Array<Object> - A list of agenda issues, each with properties like:
  • title: string - The title of the agenda issue.
  • number: number - The issue number.
  • html_url: string - The URL to the issue on GitHub.
• agendaLabel: string - The label used to identify agenda items.
• meetingNotes: string - A link or content for meeting notes.
• owner: string - The GitHub repository owner.
• repo: string - The GitHub repository name.
• title: string - The title of the issue, which can be dynamically generated.
• invitees: Array<string> - A list of invitees, if provided.
• observers: Array<string> - A list of observers, if provided.

<% const timezones = [
  'America/Los_Angeles',
  'America/Denver',
  'America/Chicago',
  'America/New_York',
  'Europe/London',
  'Europe/Amsterdam',
  'Europe/Moscow',
  'Asia/Kolkata',
  'Asia/Shanghai',
  'Asia/Tokyo',
  'Australia/Sydney'
]; %>

## Date/Time

| Timezone | Date/Time |
|----------|-----------|
<%= timezones.map((zone) => {
  const zonedDate = date.toZonedDateTimeISO(zone)
  const formatter = new Intl.DateTimeFormat('en-US', {
    weekday: 'short',
    month: 'short',
    day: '2-digit',
    year: 'numeric',
    hour: '2-digit',
    minute: '2-digit',
    hour12: true,
    timeZone: zone
  })
  const formattedDate = formatter.format(new Date(zonedDate.epochMilliseconds))
  return `| ${zone} | ${formattedDate} |`
}).join('\n') %>

Or in your local time:

* https://www.timeanddate.com/worldclock/fixedtime.html?msg=<%= encodeURIComponent(title) %>&iso=<%= date.toZonedDateTimeISO('UTC').toPlainDateTime().toString().slice(0, 16).replace(/[-:]/g, '') %>&p1=1440&ah=1

## Agenda

Extracted from **<%= agendaLabel %>** labelled issues and pull requests from **<%= owner %>/<%= repo %>** prior to the meeting.

<%= agendaIssues.map((i) => {
  return `* ${i.html_url}`
}).join('\n') %>

## Links

* Minutes: <%= meetingNotes || '' %>

## Joining the meeting

* link for participants: <%= meetingLink %>

---

Please use the following emoji reactions in this post to indicate your
availability.

* 👍 - Attending
* 👎 - Not attending
* 😕 - Not sure yet

JS API Usage

The main logic of the module is also published to npm.

$ npm i @pkgjs/meet

const maker = require('@pkgjs/meet')

;(async () => {
  const issue = await maker.meetings.createNextMeeting(client, {
    owner: 'pkgjs',
    repo: 'meet',
    schedules: []
  })
  console.log(issue) // the response from the GitHub api creating the issue
})()

Contributing

This package welcomes contributions. While the basic unit tests are runnable (npm t) Unfortunatly because it is requires access to the GitHub api it means you need to have a token with access to create the issues as part of the integration tests. To specify the key you need to create a personal access token and put it in a .env file as GITHUB_TOKEN=<TOKEN>. Then you can run npm run test:integration to run the main integration tests. To be honest this should probably be configurable, contributions welcome.