How to Connect GitHub to Verk

Your code lives in GitHub. Your tasks live in Verk. Let's connect them so your development workflow is seamless.

Why connect GitHub?

When GitHub and Verk are connected, you can:

• Automatically create GitHub issues from Verk tasks
• Trigger Verk workflows when commits are pushed
• Start tasks when pull requests are opened
• Keep your development workflow and project management in sync
• Link code changes directly to the work being tracked

What you'll need

Before you start, make sure you have:

• Admin access to the GitHub repository you want to connect (or owner/admin access to your organization)
• Admin or Member role in your Verk organization
• The repository URL or name you want to integrate

Connecting GitHub to Verk

Here's how to set up the connection:

1. Open Integrations settings

   • Log into Verk
   • Click your organization name in the top navigation
   • Go to Settings → Integrations

2. Find GitHub

   • Scroll through the available integrations
   • Find the GitHub card
   • Click the Connect button

3. Authorize with GitHub

   • You'll be redirected to GitHub's authorization page
   • Review the permissions Verk is requesting
   • Select which repositories you want to grant access to (you can choose all or specific ones)
   • Click Authorize to grant access

4. Select repositories

   • After authorization, you'll see a list of your accessible repositories
   • Check the boxes next to the repositories you want to integrate with Verk
   • Click Save Selection

5. Confirm the connection

   • You'll be redirected back to Verk
   • You should see a success message
   • The GitHub card will now show "Connected" with the number of repositories linked

That's it! GitHub is now connected to your Verk organization.

What Verk can do with GitHub

Once connected, you can use GitHub in several ways:

Create issues automatically

Turn Verk tasks into GitHub issues:

• When a bug is reported in Verk, automatically create a GitHub issue
• Sync task details, descriptions, and labels
• Link back to the original Verk task for context

Trigger workflows from commits

Start Verk workflows when code changes happen:

• When a commit is pushed to main, run deployment checks
• On new commits, update related task status
• Track development progress automatically

Respond to pull request events

Take action when PRs are opened or merged:

• Create review tasks when PRs are opened
• Notify the team in Slack when PRs need attention
• Update project status when PRs are merged
• Close related tasks automatically

Add comments to issues

Keep the conversation going:

• Post updates from Verk to GitHub issues
• Sync comments between platforms
• Keep developers informed without switching tools

Creating GitHub issues from Verk

There are two main ways to create GitHub issues from Verk:

Manual issue creation

From any task in Verk:

1. Open the task you want to convert
2. Click the ... menu in the top right
3. Select Create GitHub Issue
4. Choose the repository
5. Review the issue title and description (populated from your task)
6. Add labels if needed
7. Click Create Issue

The GitHub issue will be created and linked to your Verk task.

Automatic issue creation via workflows

Set up a workflow to automatically create issues:

1. Go to Workflows in Verk
2. Create a new workflow or edit an existing one
3. Add a trigger (e.g., "When task labeled 'bug' is created")
4. Add an action: Create GitHub Issue
5. Configure the action:
   • Select repository
   • Map task fields to issue fields
   • Add default labels
   • Set assignees
6. Save and activate the workflow

Now, whenever the trigger condition is met, a GitHub issue will be automatically created.

Setting up webhook triggers

Webhook triggers let GitHub events start Verk workflows. Here's how to set them up:

Configure webhook in GitHub

1. Go to your GitHub repository settings
2. Click Webhooks in the left sidebar
3. Click Add webhook
4. In the Payload URL, enter your Verk webhook URL:

   https://c0x9lrm7ih.execute-api.us-east-1.amazonaws.com/v1/integrations/github/webhook

5. Set Content type to application/json
6. Select which events should trigger the webhook:
   • Pushes
   • Pull requests
   • Issues
7. Make sure the webhook is set to Active
8. Click Add webhook

Create workflow in Verk

1. Go to Workflows in Verk
2. Click Create Workflow
3. Choose trigger: GitHub Event
4. Select the event type:
   • Commit pushed
   • Pull request opened
   • Pull request merged
   • Issue created
5. Add conditions if needed (e.g., only on specific branches)
6. Add actions:
   • Create a task
   • Send a notification
   • Update project status
   • Run custom automation
7. Save and activate

Now, when the selected GitHub event occurs, your Verk workflow will run automatically.

Using GitHub in workflows

Here are some powerful ways to use GitHub in your workflows:

Example: Bug tracking automation

When a task is labeled "bug" in Verk:

1. Create a GitHub issue in the main repository
2. Label it with "bug" and "priority:high"
3. Assign it to the on-call engineer
4. Post to Slack #engineering channel

Example: Pull request review process

When a PR is opened on GitHub:

1. Create a review task in Verk
2. Assign it to the code reviewer
3. Add task to the current sprint
4. Send reminder after 24 hours if not reviewed

Example: Deployment tracking

When code is merged to main branch:

1. Update the related Verk task to "deployed"
2. Add a comment with the commit SHA
3. Notify the QA team in Slack
4. Create follow-up testing tasks

Example: Feature completion flow

When a task labeled "feature" is completed in Verk:

1. Check if all related GitHub issues are closed
2. If yes, move task to "Ready for QA"
3. If no, post reminder to close remaining issues
4. Update project completion percentage

Linking tasks and issues

Keep your tasks and issues connected for better traceability:

Automatic linking

When you create a GitHub issue from a Verk task:

• The issue description includes a link back to the Verk task
• The Verk task shows a link to the GitHub issue
• Updates in either system can trigger workflows in the other

Manual linking

To link an existing GitHub issue to a Verk task:

1. Open the task in Verk
2. Find the Integrations section in the task sidebar
3. Click Link GitHub Issue
4. Paste the GitHub issue URL
5. Click Link

The connection is now established and visible in both systems.

Viewing linked items

In Verk:

• Open any task
• Look for the GitHub section in the sidebar
• Click the issue number to open it in GitHub

In GitHub:

• Open any issue created by Verk
• Look for the Verk task link in the issue description
• Click it to jump back to Verk

Managing your connection

Viewing connection status

To check if GitHub is still connected:

1. Go to Settings → Integrations
2. Look at the GitHub card
3. A green "Connected" badge with repository count means everything is working
4. If you see "Disconnected" or "Authorization expired", you'll need to reconnect

Adding or removing repositories

To change which repositories are connected:

1. Go to Settings → Integrations
2. Click Manage on the GitHub card
3. Check or uncheck repositories
4. Click Save Changes

Reconnecting GitHub

If your connection expires or is revoked:

1. Go to Settings → Integrations
2. Click Reconnect on the GitHub card
3. Follow the authorization flow again
4. Select your repositories
5. All your previous workflows will continue working with the new connection

Disconnecting GitHub

If you need to disconnect GitHub:

1. Go to Settings → Integrations
2. Click the ... menu on the GitHub card
3. Select Disconnect
4. Confirm you want to disconnect

Note: Disconnecting will disable all workflows that use GitHub actions or triggers until you reconnect.

Troubleshooting

Can't see my repository

Problem: Your repository doesn't appear in the list when connecting.

Solutions:

• Make sure you have admin access to the repository
• If it's an organization repository, check that the Verk app is approved for your GitHub organization
• Try disconnecting and reconnecting with "All repositories" access
• Verify the repository isn't archived

Webhooks not triggering workflows

Problem: GitHub events aren't starting Verk workflows.

Solutions:

• Verify the webhook is active in GitHub repository settings
• Check that the webhook URL is correct
• Look at the webhook's "Recent Deliveries" in GitHub to see if payloads are being sent
• Ensure your Verk workflow is activated (not in draft mode)
• Check that the event type in your workflow matches the webhook events

Issues not being created

Problem: Workflows run but GitHub issues aren't created.

Solutions:

• Verify you have push access to the repository
• Check that the GitHub connection hasn't expired
• Make sure the repository still exists and isn't archived
• Look for error messages in the workflow execution log
• Try creating an issue manually to test the connection

"Permission denied" errors

Problem: Getting errors about insufficient permissions.

Solutions:

• Check that you granted the necessary permissions during authorization
• Verify your GitHub account has write access to the repository
• Go to GitHub Settings → Applications → Authorized OAuth Apps and check Verk's permissions
• Try disconnecting and reconnecting with full permissions

Linked issues showing as broken

Problem: Links between tasks and issues aren't working.

Solutions:

• Verify the GitHub issue still exists (it might have been deleted)
• Check that the repository hasn't been made private or you've lost access
• Try unlinking and relinking the issue
• Refresh the Verk page to see if it's just a display issue

Privacy and permissions

What Verk can access

When you connect GitHub, Verk can:

• Read repository information (name, description, branches)
• Create issues in connected repositories
• Read issue data to sync with tasks
• Receive webhook notifications for selected events
• Add comments to issues

What Verk cannot access

Verk cannot:

• Read your code or file contents
• Modify code or commit changes
• Access repositories you haven't explicitly connected
• Delete repositories or issues
• Access private repositories unless you grant permission

Revoking access

You can revoke Verk's access at any time:

From GitHub:

1. Go to GitHub Settings
2. Click Applications in the left sidebar
3. Go to Authorized OAuth Apps
4. Find "Verk" and click Revoke

From Verk:

1. Go to Settings → Integrations
2. Click Disconnect on the GitHub card

Best practices

Issue management

• Use consistent labels between Verk and GitHub for easier automation
• Include context in issue descriptions so developers have all the information
• Link related issues and tasks for better traceability
• Close issues promptly when work is completed

Workflow design

• Start with simple workflows and add complexity gradually
• Test workflows with a test repository first
• Use branch filters to avoid triggering workflows on every commit
• Add error handling for cases where actions fail

Repository organization

• Connect only the repositories you actively use with Verk
• Create separate workflows for different repositories if they have different processes
• Use consistent naming conventions across projects
• Document your integration setup for team members

Security

• Regularly review which repositories are connected
• Use fine-grained access tokens when possible
• Monitor webhook activity for unusual patterns
• Remove integration access for team members who leave

Common workflows

Development team

Bug report to fix:

1. Customer reports bug → Task created in Verk
2. Task labeled "bug" → GitHub issue created automatically
3. Developer commits fix → Verk task updated with commit link
4. PR merged → Task moved to "Ready for QA"

Feature development:

1. Feature task created in Verk
2. Create GitHub issue from task
3. Link PR to issue in commit message
4. PR merged → Task auto-completed

Operations team

Deployment tracking:

1. Deployment task created in Verk
2. Workflow monitors main branch
3. On merge to main → Update deployment task
4. Run post-deployment checks

Product team

Release planning:

1. Create milestone in Verk
2. Generate GitHub issues for all milestone tasks
3. Track progress via linked issues
4. Auto-update milestone completion in Verk

Getting help

If you run into issues not covered here:

• Check the Verk status page for known integration issues
• Review GitHub's webhook delivery logs for error messages
• Contact your Verk organization admin
• Reach out to Verk support with specific error messages and workflow details

The GitHub integration helps bridge the gap between project management and development, keeping everyone on the same page.