Monday.com GitHub Integration

Overview

Every Pull Request in Pivot repositories must include a Monday.com task link. This is enforced automatically by GitHub Actions - PRs without proper Monday links cannot be merged.

Why We Require Monday Links

The PR description link is for humans - reviewers can see which task this PR relates to.

The commit link is critical for automation - when code moves through the deployment pipeline (dev → main → production), the system reads Monday task IDs from the commits to update their status. Without Monday links in commits, we lose track of tasks as they progress through environments.

How Status Tracking Works

When code is fast-forwarded from development to main (or main to production), there's no PR - just a git push. The webhook receives this push event and:

Reads all commits in the push
Extracts Monday task IDs from commit messages
Updates the status of each referenced task

This is why commits MUST have Monday links - without them, we can't track which tasks reached staging or production.

Event	How Tasks Are Found	Status Set
PR opened	From PR description	Code Review
PR merged to development	From PR description	Deployed to Dev
Push to main (fast-forward)	From commit messages	Deployed to non-production
Push to production (fast-forward)	From commit messages	Deployed to production

What's Required

Requirement	Where	Enforced By	Why
Monday link in PR description	PR body	GitHub Actions	For reviewers + PR-level tracking
Monday link in at least ONE commit	Commit message	GitHub Actions	For deployment pipeline tracking
Same task ID in PR and commits	Both	GitHub Actions	Prevents mismatched task references

All three requirements must be met for the PR to pass validation and be mergeable. The PR description and at least one commit must reference the same Monday task to ensure consistency.

Integration Flow

What You Get

Automatic Notifications:

Push a commit with a Monday link → notification appears in the Monday task
No setup required, works immediately
See commit details directly in Monday where you're already tracking work

Optional Validation:

Install a git hook to validate Monday links before committing
Prevents commits without Monday links (if you want that)
Easy to bypass when needed

How to Use

Writing Commits

Include a Monday.com task URL in your commit message:

git commit -m "Fix authentication bug

https://pivotapp.monday.com/boards/4176868787/pulses/18382176781"

The commit will automatically appear as a notification in that Monday task when you push.

Supported URL Formats

https://pivotapp.monday.com/boards/[board_id]/pulses/[task_id]
https://pivotapp.monday.com/boards/[board_id]/views/[view_id]/pulses/[task_id]

Both formats work - you can copy the URL directly from your browser.

Example Notification

When you push, the Monday task gets a notification like this:

🔧 GitHub Commit

Repository: pivotteam/pivot
Branch: main
Commit: abc1234

Message: Fix authentication bug

👤 Author: Your Name
🔗 View Commit: https://github.com/pivotteam/pivot/commit/abc1234

Pull Request Validation (Required)

Every Pull Request is automatically validated by GitHub Actions. PRs that fail validation cannot be merged.

Validation Rules

Important: The validation script fails hard if it cannot retrieve PR commits. If the git ref resolution fails, the check will block the merge rather than silently passing. This prevents accidental bypasses when the CI environment has unexpected ref states.

What You Need to Do

1. Include a Monday link in your PR description:

## Summary
Fixed the authentication bug that was causing login failures.

## Monday Task
https://pivotapp.monday.com/boards/4176868787/pulses/18387094473

2. Include a Monday link in at least ONE commit:

git commit -m "Fix authentication bug

https://pivotapp.monday.com/boards/4176868787/pulses/18387094473"

Both are required. The PR description links the PR to the task for reviewers. The commit links the code change to the task in git history forever.

Example: Passing Validation

Validating Monday.com links in PR...

PR #123: Fix authentication bug

CHECK 1: PR Description
─────────────────────────────────────────
  ✓ Found Monday link(s) in PR description: 18387094473

CHECK 2: Commits
─────────────────────────────────────────
  abc1234: Fix authentication bug
    ↳ ✓ Monday link(s): 18387094473
  def5678: Add unit tests
    ↳ No Monday link

CHECK 3: Task ID Consistency
─────────────────────────────────────────
  ✓ Matching task(s): 18387094473

Validating 1 unique Monday task(s)...
─────────────────────────────────────────
  ✓ Task 18387094473: "Fix login redirect issue"

═══════════════════════════════════════════
VALIDATION SUMMARY
═══════════════════════════════════════════
PR Description has link:  ✓ Yes
Commit(s) have link:      ✓ Yes
Task IDs match:           ✓ Yes
Valid Monday tasks:       1
═══════════════════════════════════════════

PR validation passed!

Example: Failing Validation

═══════════════════════════════════════════
VALIDATION SUMMARY
═══════════════════════════════════════════
PR Description has link:  ✗ No
Commit(s) have link:      ✓ Yes
Task IDs match:           ✓ Yes
Valid Monday tasks:       1
═══════════════════════════════════════════

VALIDATION FAILED

  • PR description must contain a Monday.com task link

Required format: https://pivotapp.monday.com/boards/XXX/pulses/YYY
To bypass: add [skip-monday] to PR title or description

Bypassing Validation

In rare cases, you may need to merge without a Monday link (e.g., urgent hotfixes, automated PRs).

Add [skip-monday] to your PR title or description:

[skip-monday] Emergency production hotfix

Use this sparingly - every PR should ideally be linked to a task.

PR Lifecycle Tracking

The system automatically tracks your PR and updates Monday accordingly.

PR Lifecycle Flow

What Happens Automatically

When you open a PR:

Status automatically set to "Code Review"
Notification posted to the Monday task with PR details
Includes PR number, title, author, and link to the PR

When the PR is merged to development:

Status automatically set to "Deployed to Dev"
Merge notification posted to the Monday task
Shows PR was successfully merged and deployed to development environment

When code reaches main branch:

Status automatically set to "Deployed to non-production"
Notification posted confirming code is in staging environment
This happens when development is merged to main

When code reaches production branch:

Status automatically set to "Deployed to production"
Notification posted confirming code is live
This happens when main is merged to production

Preview URLs (for pivot web app):

Firebase Hosting preview URL automatically posted to Monday
Clickable link to test your changes before merging
Posted once per PR

Tasks vs Subtasks

The integration automatically handles both tasks and subtasks. When you link a Monday item in your PR:

Tasks live on the main SPRINTS DEV board (status column: status9)
Subtasks live on the Subitems board (status column: status)

The system detects this automatically - you don't need to do anything different!

Example Monday Updates

For a single PR, you'll see these updates in your Monday task:

PR Opened: "Pull Request #123 opened - Feature: Add user authentication"
Preview URL: "Preview Deployment - PR #123 - https://pivot-dev-59310--pr-123-abc.web.app"
Commits: "3 commits, 12 files changed" (updated as you push more commits)
PR Merged: "Pull Request #123 merged" + status columns updated

All updates are separate and clearly labeled, so you can see the full PR lifecycle at a glance.

Branch Strategy

Feature branches:

PR opened/merged notifications posted to Monday
Preview URLs posted (if available)
Commits tracked via PR (not posted individually)

Main branch:

Commit notifications posted directly to Monday
Each commit appears as a consolidated update

This prevents duplicate notifications and keeps your Monday tasks clean.

Installing the Git Hook (Optional)

The git hook validates your commit messages locally before they're committed. This is optional but recommended.

Installation

After cloning a repository:

# Navigate to repository root
cd /path/to/pivot  # or pivot-kpi, pivot-mobile, etc.

# Install the hook (one-time setup)
./.github/hooks/install.sh

You should see:

✅ Git hook installed successfully!

The commit-msg hook will now validate that all commits include a Monday.com task link.

What the Hook Does

Without Monday link - rejected:

$ git commit -m "Fix authentication bug"

❌ COMMIT REJECTED: Missing Monday.com task link

Every commit must include a Monday.com task URL like:
  https://pivotapp.monday.com/boards/XXX/pulses/YYY

To bypass this check (for testing/CICD), add [skip-monday] to your commit message.
To skip this hook entirely, use: git commit --no-verify

With Monday link - accepted:

$ git commit -m "Fix authentication bug

https://pivotapp.monday.com/boards/4176868787/pulses/18382176781"

[main abc1234] Fix authentication bug
 1 file changed, 5 insertions(+)

Bypassing the Hook

Sometimes you need to commit without a Monday link:

Option 1: Use [skip-monday] tag

git commit -m "WIP: Testing something [skip-monday]"

Option 2: Skip all hooks

git commit --no-verify -m "Emergency hotfix"

Why Hooks Must Be Manually Installed

Git hooks are not automatically installed for security reasons. If hooks auto-ran when you clone a repository, malicious code could execute on your machine.

Key points:

Hooks must be manually installed by each developer
This is a Git security feature to prevent arbitrary code execution
The installation script is a one-time setup per clone
Installing the hook is optional but proves you're committed to the process

Historical note: You may remember server-side linters or GitHub Actions that validated commits automatically. Those worked but blocked fast-forward merges between environments (dev → stage → production). The current approach is intentionally simple: optional local validation that doesn't interfere with deployment workflows.

Troubleshooting

Webhook notification not appearing in Monday

1. Check your commit message

Make sure the Monday link is on its own line
Copy the URL directly from your browser
Verify the task ID is correct

2. Check webhook delivery

Go to repository Settings → Webhooks in GitHub
Click on the webhook URL
Check recent deliveries for errors

3. Still not working?

Ask in the team channel - webhook might be down
Check if other commits are getting posted

Hook not working

Hook not blocking commits without Monday links:

# Verify hook is installed
ls -la .git/hooks/commit-msg

# If not there, reinstall
./.github/hooks/install.sh

# Make sure it's executable
chmod +x .git/hooks/commit-msg

Hook blocking commits incorrectly:

The hook might be from an old version. Reinstall:

./.github/hooks/install.sh

Need to commit without Monday link

Use one of the bypass options:

# Option 1: Add [skip-monday] tag
git commit -m "Emergency fix [skip-monday]"

# Option 2: Skip all hooks
git commit --no-verify -m "Emergency fix"

Repositories Using This Integration

✅ pivot (main web app)
✅ pivot-kpi (KPI dashboard)
✅ pivot-mobile (React Native app)
⏳ pivot-jobs (planned)

FAQs

Q: Is the Monday link validation mandatory? A: Yes. PRs without Monday links in both the PR description AND at least one commit will fail the "Monday Link Required" check and cannot be merged.

Q: Do I have to install the git hook? A: No, the local git hook is optional. However, the GitHub Actions validation is mandatory - it runs automatically on every PR. The hook just helps you catch missing links earlier.

Q: What if I forget to include a Monday link in my PR? A: The PR will be created but will fail the "Monday Link Required" check. Edit your PR description to add the Monday link, and the check will re-run automatically.

Q: What if I forget to include a Monday link in my commit? A: If none of your commits have a Monday link, the validation will fail. You can either:

Amend your last commit to add the link: git commit --amend
Add a new commit with the Monday link
Use [skip-monday] in the PR title (not recommended)

Q: Can I link multiple Monday tasks in one PR? A: Yes! Just include multiple Monday URLs in your PR description and/or commits. All linked tasks will receive notifications.

Q: What if I need to merge something unrelated to a Monday task? A: Add [skip-monday] to your PR title or description. Use this sparingly - it should be rare (e.g., dependency updates, automated PRs).

Q: Does this slow down my PRs? A: The validation takes about 10-15 seconds. The local hook (if installed) is instant.

Q: Will this create duplicate notifications? A: No. The system detects duplicates and only posts each commit once per Monday task. Preview URLs are only posted once per PR.

Q: What status columns get updated? A: The status progresses through the deployment pipeline:

Code Review - when PR is opened
Deployed to Dev - when merged to development
Deployed to non-production - when code reaches main branch
Deployed to production - when code reaches production branch

Q: What if the validation says my Monday task doesn't exist? A: Double-check the task URL is correct. The system validates that the task actually exists in Monday.com. Make sure you're copying the URL from an actual task, not a board or view.

Need Help?

For implementation details, architecture, or setting up the integration for new repositories, see:

Monday GitHub Integration - Implementation Guide

For general questions about using the integration, ask in the team channel.

Overview​

Why We Require Monday Links​

How Status Tracking Works​

What's Required​

Integration Flow​

What You Get​

How to Use​

Writing Commits​

Supported URL Formats​

Example Notification​

Pull Request Validation (Required)​

Validation Rules​

What You Need to Do​

Example: Passing Validation​

Example: Failing Validation​

Bypassing Validation​

PR Lifecycle Tracking​

PR Lifecycle Flow​

What Happens Automatically​

Tasks vs Subtasks​

Example Monday Updates​

Branch Strategy​

Installing the Git Hook (Optional)​

Installation​

What the Hook Does​

Bypassing the Hook​

Why Hooks Must Be Manually Installed​

Troubleshooting​

Webhook notification not appearing in Monday​

Hook not working​

Need to commit without Monday link​

Repositories Using This Integration​

FAQs​

Need Help?​