> ## Documentation Index
> Fetch the complete documentation index at: https://docs.navisops.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect Navis Ops to GitHub

> Link GitHub repositories to Navis Ops projects and trigger workflows from GitHub events using webhooks. Keep your code and tasks in sync automatically.

The GitHub integration connects your code repositories to your Navis Ops workspace. You can link any repository to a project so that context is always one click away, and you can trigger Navis Ops workflows automatically when events happen in GitHub — such as a push, a pull request opening, or an issue being filed.

## What the integration does

Navis Ops works with GitHub in two directions:

* **Project linking** — attach a repository URL to a project using a custom field so your team can navigate directly from a task or project to the relevant code.
* **Workflow triggering** — GitHub sends webhook events to Navis Ops, which kicks off a workflow. Use this to create tasks from GitHub issues, update task statuses on pull request merges, or post Slack notifications when a deployment completes.

## Link a repository to a project

Navis Ops doesn't require a formal GitHub OAuth connection to link repositories. You add the repository URL as a custom field on your project.

<Steps>
  <Step title="Open your project">
    Navigate to the project you want to link a repository to.
  </Step>

  <Step title="Add a URL custom field">
    Go to the project's **Settings** tab and add a new custom field. Set the type to **URL** and name it something like "GitHub repository."
  </Step>

  <Step title="Paste the repository URL">
    Enter the full GitHub repository URL (for example, `https://github.com/your-org/your-repo`). The field renders as a clickable link anywhere the project is displayed.
  </Step>
</Steps>

<Tip>
  You can add the repository URL field to your project type so that every project created with that type automatically includes the field. Go to **Settings → Project types** to configure this.
</Tip>

## Trigger workflows from GitHub events

GitHub can send webhook events to a Navis Ops workflow whenever something happens in your repository — a push, a new pull request, a new issue, a deployment, or any other event GitHub supports.

<Steps>
  <Step title="Create a workflow with a webhook trigger">
    In Navis Ops, go to **Workflows** and create a new workflow. Choose **Webhook** as the trigger. Navis Ops generates a unique endpoint URL for this workflow.
  </Step>

  <Step title="Copy the webhook endpoint URL">
    Copy the endpoint URL shown in the webhook trigger settings. You'll paste this into GitHub.
  </Step>

  <Step title="Add the webhook in GitHub">
    In your GitHub repository, go to **Settings → Webhooks → Add webhook**.

    * Paste your Navis Ops endpoint URL into the **Payload URL** field.
    * Set **Content type** to `application/json`.
    * In the **Secret** field, paste your webhook secret from the Navis Ops trigger settings (see [securing your webhook](/guides/integrations/webhooks#securing-your-webhook)).
    * Choose which events to send. For most use cases, select **Let me select individual events** and pick the specific events you care about.
  </Step>

  <Step title="Build the rest of the workflow">
    Back in Navis Ops, add nodes after the webhook trigger to act on the incoming data. Use the variable picker to access fields from the GitHub payload (for example, `{{trigger.repository.name}}` or `{{trigger.pull_request.title}}`).
  </Step>

  <Step title="Activate the workflow">
    Save and activate the workflow. GitHub delivers events to the endpoint and the workflow runs each time.
  </Step>
</Steps>

## Example: GitHub push creates a task in Navis Ops

This workflow creates a task in Navis Ops each time a push lands on the `main` branch — useful for tracking deployments or triggering a review checklist.

<Steps>
  <Step title="Create a webhook-triggered workflow">
    Create a new workflow with a **Webhook** trigger. Copy the endpoint URL.
  </Step>

  <Step title="Register the webhook in GitHub">
    In your repository's webhook settings, paste the endpoint URL, set the content type to `application/json`, and select the **Push** event.
  </Step>

  <Step title="Add a condition node">
    Add a **Condition** node that checks `trigger.ref` equals `refs/heads/main` so the workflow only continues on pushes to the main branch.
  </Step>

  <Step title="Add a Create Task node">
    Add a **Create Task** node. Set:

    * **Title** → `Deploy: {{trigger.repository.name}} pushed by {{trigger.pusher.name}}`
    * **Project** → select your deployment-tracking project
    * **Due date** → today
  </Step>

  <Step title="Test with a push">
    Make a push to your main branch. The task should appear in Navis Ops within seconds.
  </Step>
</Steps>

<Note>
  GitHub retries webhook deliveries if your endpoint returns an error or doesn't respond within 10 seconds. Navis Ops acknowledges the request immediately, so duplicate tasks from retries are unlikely — but if you see them, add a condition that checks a unique field from the payload (like the commit SHA) to deduplicate.
</Note>

## See also

<CardGroup cols={2}>
  <Card title="Custom webhooks" icon="webhook" href="/guides/integrations/webhooks">
    Full guide to inbound and outbound webhooks, payload access, and security.
  </Card>

  <Card title="Workflow nodes" icon="circle-nodes" href="/guides/workflows/nodes">
    All node types available to act on GitHub event data.
  </Card>

  <Card title="Workflow triggers" icon="bolt" href="/guides/workflows/triggers">
    Overview of all trigger types including webhook, schedule, and entity triggers.
  </Card>

  <Card title="Slack integration" icon="slack" href="/guides/integrations/slack">
    Post to Slack when GitHub events trigger a Navis Ops workflow.
  </Card>
</CardGroup>