Scheduled Content Publishing With GitHub Actions

Some content has to appear at a particular moment: a product launch page at 09:00 Berlin time, release notes when the release ships, a security advisory when the embargo lifts. Static sites publish by building, so "publish at 09:00" means "merge and deploy at 09:00". Filtering future-dated posts at build time handles the simple case, as in Scheduling Content Publication With Cron-Triggered Builds, but it requires the content to sit on the main branch beforehand — visible in the repository, in preview deploys and to anyone who knows the URL pattern — and it only works for content, not for the navigation changes, redirects and component updates a launch usually includes.

This guide schedules pull request merges instead: a reviewed pull request carries a publish time, and a scheduled workflow merges it when that time arrives, which triggers the normal deploy. It is set up for a product documentation and marketing site whose launches combine pages, navigation and redirects in one change. It belongs to Content Workflows for Documentation Teams.

Prerequisites

• Branch protection on main requiring review and passing checks.
• A deploy workflow that runs on pushes to main.
• A GitHub App or fine-grained token that can merge pull requests (the default GITHUB_TOKEN cannot trigger further workflows, so a merge made with it would not start the deploy).

How It Works

Step 1: Mark Pull Requests With a Publish Time

Authors add one line to the pull request description, with an explicit time zone:

publish-at: 2026-10-14 09:00 Europe/Berlin

A label scheduled makes them easy to list. Writing the zone name rather than an offset avoids daylight-saving mistakes; the scheduler converts it to UTC.

Step 2: The Scheduler Workflow

name: scheduled-merge
on:
  schedule: [{ cron: '7,22,37,52 * * * *' }]
  workflow_dispatch:
jobs:
  merge-due:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/create-github-app-token@v1
        id: app
        with: { app-id: '${{ vars.MERGE_APP_ID }}', private-key: '${{ secrets.MERGE_APP_KEY }}' }
      - uses: actions/github-script@v7
        with:
          github-token: ${{ steps.app.outputs.token }}
          script: |
            const prs = await github.paginate(github.rest.pulls.list, { ...context.repo, state: 'open' });
            for (const pr of prs.filter(p => p.labels.some(l => l.name === 'scheduled'))) {
              const m = /publish-at:\s*(\d{4}-\d\d-\d\d \d\d:\d\d)\s+([\w/]+)/.exec(pr.body || '');
              if (!m) continue;
              const due = zonedToUtc(m[1], m[2]);            // small helper using Intl
              if (Date.now() < due) continue;
              const { data: full } = await github.rest.pulls.get({ ...context.repo, pull_number: pr.number });
              if (full.mergeable_state !== 'clean') {
                await github.rest.issues.createComment({ ...context.repo, issue_number: pr.number,
                  body: `Scheduled time passed but this PR is not mergeable (${full.mergeable_state}). Not published.` });
                continue;
              }
              await github.rest.pulls.merge({ ...context.repo, pull_number: pr.number, merge_method: 'squash' });
              core.notice(`Merged #${pr.number}, due ${m[1]} ${m[2]}`);
            }

The cron runs at minutes 7, 22, 37 and 52, avoiding the top of the hour when GitHub's scheduler is busiest. mergeable_state === 'clean' is true only when required reviews and checks have passed, so branch protection is enforced by GitHub, not by the script.

Step 3: Confirm the Deploy

Merging is not publishing. A step in the deploy workflow, when the commit came from a scheduled merge, comments on the original pull request with the time the site went live, or with a failure notice:

      - if: always() && contains(github.event.head_commit.message, '(scheduled)')
        uses: actions/github-script@v7
        with:
          script: |
            const ok = '${{ job.status }}' === 'success';
            // find PR number from the squash commit message "(#123)" and comment

The squash commit message includes (scheduled) because the scheduler sets commit_title. Authors watching for their launch get a notification either way.

Step 4: Rehearse Important Launches

For launches where a failed build at 09:00 would be costly, the pull request's own preview deploy is the rehearsal: it builds the exact merged result (GitHub Actions builds pull requests against a merge commit), and the checks must be green for the scheduler to merge at all. An hour before, the scheduler posts a reminder comment, and if main has moved, the author can update the branch and let checks rerun.

Choosing Between Build-Time Dates and Scheduled Merges

The site uses both mechanisms, for different content. Blog posts carry a date in front matter and are filtered at build time by a daily scheduled build; they need no coordination and nobody minds if a post appears at 06:00 or 06:20. Launches use scheduled merges, because they change more than one file and must not be visible early.

The cost of scheduled merges is a GitHub App and one workflow file; the cost of build-time dates is that future content is public in the repository and in every preview. Teams with a public repository should be especially careful with the second: a future-dated post merged to main of a public repository is readable by anyone the moment it is merged, long before the build publishes it.

Embargoed Content and Previews

Preview deploys of an embargoed pull request are reachable by anyone with the URL. For embargoed security advisories the team uses password-protected previews, as in Password-Protecting Preview Deployments, and keeps such pull requests in a private fork until a few hours before the scheduled time. For ordinary launches, unguessable preview URLs and noindex headers have been enough.

Cancelling or Moving a Launch

Plans change. Removing the scheduled label cancels a scheduled merge; editing the publish-at line moves it. Both are ordinary edits to the pull request, visible in its history, so there is no separate scheduling system to keep in sync. The scheduler's log in the Actions tab records every decision it made for every pull request — skipped as not due, skipped as not mergeable, merged — which answered the one question that came up after a launch: "why did it go live at 09:22 and not 09:07?" (a required check had been re-run at 09:05 and was still running at 09:07).

Measured Impact

Over six months, compared with the previous practice of a person merging by hand at launch time:

Pitfalls & Rollback

• Merging with GITHUB_TOKEN. The deploy workflow will not trigger; use an app token.
• Times without zones. Write the zone name; let the script handle daylight saving.
• Exact-minute expectations. Scheduled workflows run late; allow 15 minutes.
• Skipping the deploy check. A merge is not a launch until the deploy succeeds.
• Rollback: reverting the merged pull request through the normal pipeline unpublishes it; for an urgent removal, the host's rollback to the previous deploy is faster.

Conclusion

Scheduling pull request merges with GitHub Actions publishes whole launches — pages, navigation and redirects — at a set time, keeps embargoed content off the main branch until then, and leaves review and checks to branch protection. Over 30 launches it published a median of 9 minutes after the target with nobody at a keyboard, and never early.

FAQ

How is this different from filtering future-dated posts at build time?

Build-time filtering publishes content whose date has passed on the next build, which suits blog posts but requires the content to be merged in advance, visible in the repository and in preview deploys. Scheduled merges keep the change in an unmerged pull request until the scheduled time, so embargoed content is not on the main branch, and the change can include code, navigation and redirects as well as content.

How accurate is the timing of a scheduled GitHub Actions workflow?

Scheduled workflows run on a best-effort basis and are often delayed by several minutes, more at the top of the hour when load is highest. Running the check every 10 or 15 minutes at an off-peak minute, and allowing for the build and deploy time, gives launches within about 15 minutes of the target, which is fine for most content and not for exact-second embargoes.

What happens if the build fails at the scheduled time?

The merge happens but the deploy does not, so the content is not live. The workflow should check that the deploy succeeded and notify the owner of the pull request if it did not. For important launches, merging into a release branch and building a preview an hour before the scheduled time catches failures early.

How do I prevent a scheduled pull request from merging without review?

Rely on branch protection. The scheduler only merges pull requests that GitHub considers mergeable, which with protection rules means required reviews and checks have passed. A pull request missing approval at its scheduled time is skipped and its author notified.

Related

• Parent: Content Workflows for Documentation Teams — content from writer to production.
• Scheduling Content Publication With Cron-Triggered Builds — the build-time filtering alternative.
• Deploying to Multiple Environments From One Workflow — the deploy pipeline this triggers.
• Release Notes and Changelogs from Git — content that is often scheduled.
• Git-Based CMS Options for Static Sites Compared — editors creating the scheduled pull requests.