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

# GitHub

> Repositories, issues, pull requests and webhooks — give your agents full developer lifecycle access through a single OAuth connection.

<div className="xagh-hero xc-border">
  <div className="exp-eyebrow mxp-rise">DEVELOPER LIFECYCLE</div>

  <h2 className="mxp-hero-title mxp-rise" style={{animationDelay:'0.06s'}}>
    An agent that lives <span style={{background:'linear-gradient(90deg,#24A4FF,#9000FF,#E3008E)',WebkitBackgroundClip:'text',backgroundClip:'text',color:'transparent'}}>inside your repo.</span>
  </h2>

  <p className="mxp-hero-dek mxp-rise" style={{animationDelay:'0.13s'}}>
    Triage the backlog. Comment on the PR. Dispatch an Actions workflow. Draft the release notes. One OAuth connection wires 33 verified GitHub tools into every agent you trust with it — no webhook receiver to host, no dashboard to watch.
  </p>
</div>

<div className="w-full py-10 xc-rise">
  <div className="actionist-tight flex flex-col gap-2 mb-6">
    <span className="actionist-section-eyebrow">Capabilities</span>
    <h2 className="text-2xl md:text-3xl font-semibold tracking-tight text-gray-900 dark:text-gray-50">33 tools across the full developer lifecycle.</h2>

    <p className="text-base text-gray-600 dark:text-gray-400 max-w-3xl">
      GitHub tools cover eight service areas. An agent can read the repo, triage issues, review code, trigger CI, and manage releases — all in one conversation.
    </p>
  </div>

  <div className="mxs-limits" style={{margin:'20px 0'}}>
    <div className="mxs-limit xagh-stat"><b>33</b><span>verified GitHub tools</span></div>
    <div className="mxs-limit xagh-stat"><b>8</b><span>service areas covered</span></div>
    <div className="mxs-limit xagh-stat"><b>1</b><span>OAuth connection needed</span></div>
    <div className="mxs-limit xagh-stat"><b>0</b><span>webhook receivers to host</span></div>
  </div>

  <AccordionGroup>
    <Accordion title="Files and repositories" icon="folder" defaultOpen={true}>
      Read file contents, list repositories for a user or org, retrieve a repo's license, and pull traffic analytics (popular paths and referrers). Use these to give an agent full context before it drafts a PR comment or creates an issue.
    </Accordion>

    <Accordion title="Issues" icon="circle-dot">
      Create, edit, comment on, and lock issues; fetch all open issues by repo or by user. The issue tools are the fastest path to automated triage: point an agent at your inbox and have it label, prioritize, and respond — unattended.
    </Accordion>

    <Accordion title="Pull requests and reviews" icon="git-pull-request">
      List open pull requests, create code reviews, retrieve and update review sets. Wire a trigger on PR-opened to fire an agent that checks for missing tests, leaves a first-pass comment, and requests reviewers.
    </Accordion>

    <Accordion title="Releases" icon="tag">
      Create, update, delete, and list releases. A scheduled agent can pull all merged PRs since the last release, group them by label, and publish a formatted release note — no manual write-up required.
    </Accordion>

    <Accordion title="GitHub Actions workflows" icon="play">
      List, enable, disable, get usage, and dispatch workflow runs. An agent can trigger a staging deploy, check its status, and post the result to Slack — all from a single chat message.
    </Accordion>

    <Accordion title="Users and organizations" icon="users">
      Get user repositories, retrieve issues assigned to a user, and invite members to an organization. Use org tools in onboarding automations that set up repo access when a new teammate joins.
    </Accordion>
  </AccordionGroup>

  <Tip>
    Combine `github:*` tools (GitHub REST API) with the bundled `git-official` MCP (local Git) for a coding agent that can stage commits and file the PR in a single run. The two are separate — `git-official` operates on local repos; `github:*` calls the remote GitHub API.
  </Tip>
</div>

<div className="w-full py-10 xc-rise">
  <div className="actionist-tight flex flex-col gap-2 mb-6">
    <span className="actionist-section-eyebrow">Setup</span>
    <h2 className="text-2xl md:text-3xl font-semibold tracking-tight text-gray-900 dark:text-gray-50">Connect GitHub.</h2>

    <p className="text-base text-gray-600 dark:text-gray-400 max-w-3xl">
      OAuth is the recommended path — your credentials never touch the desktop, and one connection covers every agent you authorize. A Personal Access Token stored in the Credentials Vault is the alternative for narrower, read-only access.
    </p>
  </div>

  <Steps>
    <Step title="Open the Apps catalog">
      In the Actionist sidebar click <strong>Apps</strong>. Search for "GitHub" or browse the <strong>Code & Source Control</strong> category filter to find the GitHub card.
    </Step>

    <Step title="Click Connect GitHub">
      Open the GitHub detail page and click <strong>Connect GitHub</strong>. Actionist creates a one-shot OAuth handoff URL and opens your system browser to GitHub's consent screen.
    </Step>

    <Step title="Authorize the OAuth app">
      GitHub requests four scopes: `repo`, `admin:repo_hook`, `read:user`, and `user:email`. Authorize the app — GitHub redirects to the Actionist backend callback.
    </Step>

    <Step title="Wait for confirmation">
      Actionist polls the backend every 2 seconds. When the handshake completes, the connection card updates with your connected account name and email. The session window is 10 minutes — if it expires, click <strong>Connect GitHub</strong> again.
    </Step>
  </Steps>

  {/* TODO(image): github-connect — IMAGE SPEC: GitHub app detail page in the Apps catalog (pre-auth state). Show the GitHub card header with the name 'GitHub', the description 'Repositories, issues, pull requests & webhooks.', the OAuth badge, and the 'Connect GitHub' button. Dark background, purple-violet accent on the card. — replace this CSS mock with the real screenshot */}

  <div className="xagh-mock-connect">
    <div className="xagh-mock-topbar">
      <span className="xagh-mock-topbar-dot" />

      <span className="xagh-mock-topbar-dot" />

      <span className="xagh-mock-topbar-dot" />

      <span className="xagh-mock-topbar-label">Apps — Actionist</span>
    </div>

    <div className="xagh-mock-body">
      <div className="xagh-mock-sidebar">
        <div className="xagh-mock-row xagh-mock-row-sm xagh-mock-row-active" />

        <div className="xagh-mock-row xagh-mock-row-sm" />

        <div className="xagh-mock-row xagh-mock-row-sm" />

        <div className="xagh-mock-row xagh-mock-row-sm" />
      </div>

      <div className="xagh-mock-card-area">
        <div className="xagh-mock-card">
          <div className="xagh-mock-card-header">
            <div className="xagh-mock-gh-icon">
              <svg viewBox="0 0 24 24" fill="currentColor" width="22" height="22">
                <path d="M12 0C5.37 0 0 5.37 0 12c0 5.31 3.435 9.795 8.205 11.385.6.105.825-.255.825-.57 0-.285-.015-1.23-.015-2.235-3.015.555-3.795-.735-4.035-1.41-.135-.345-.72-1.41-1.23-1.695-.42-.225-1.02-.78-.015-.795.945-.015 1.62.87 1.845 1.23 1.08 1.815 2.805 1.305 3.495.99.105-.78.42-1.305.765-1.605-2.67-.3-5.46-1.335-5.46-5.925 0-1.305.465-2.385 1.23-3.225-.12-.3-.54-1.53.12-3.18 0 0 1.005-.315 3.3 1.23.96-.27 1.98-.405 3-.405s2.04.135 3 .405c2.295-1.56 3.3-1.23 3.3-1.23.66 1.65.24 2.88.12 3.18.765.84 1.23 1.905 1.23 3.225 0 4.605-2.805 5.625-5.475 5.925.435.375.81 1.095.81 2.22 0 1.605-.015 2.895-.015 3.3 0 .315.225.69.825.57A12.02 12.02 0 0 0 24 12c0-6.63-5.37-12-12-12z" />
              </svg>
            </div>

            <div className="xagh-mock-card-meta">
              <span className="xagh-mock-card-name">GitHub</span>
              <span className="xagh-mock-card-desc">Repositories, issues, pull requests & webhooks.</span>
            </div>

            <span className="xagh-mock-oauth-badge">OAuth</span>
          </div>

          <div className="xagh-mock-card-divider" />

          <div className="xagh-mock-row xagh-mock-row-full xagh-mock-row-xs" />

          <div className="xagh-mock-row xagh-mock-row-full xagh-mock-row-xs" style={{width:'75%'}} />

          <div className="xagh-mock-card-footer">
            <button className="xagh-mock-connect-btn" type="button">Connect GitHub</button>
          </div>
        </div>
      </div>
    </div>
  </div>

  <Note>
    <strong>PAT alternative.</strong> Store a Personal Access Token in <strong>Settings → Credentials Vault</strong> (provider: `github`, display name e.g. `"GitHub PAT — work"`). Any MCP or skill that declares `env:GITHUB_TOKEN` picks it up automatically — one entry covers every tool that needs it.
  </Note>
</div>

<div className="w-full py-10 xc-rise">
  <div className="actionist-tight flex flex-col gap-2 mb-6">
    <span className="actionist-section-eyebrow">Agents</span>
    <h2 className="text-2xl md:text-3xl font-semibold tracking-tight text-gray-900 dark:text-gray-50">Give an agent access to GitHub tools.</h2>
  </div>

  <Columns cols={2}>
    <Card title="Enable via the Tools tab" icon="wrench">
      Open any agent in the <strong>Agents</strong> studio → <strong>Tools</strong> tab. GitHub tools (`github:issues:create`, `github:repositories:getIssues`, and the rest) appear there once the connection is established — toggle the ones this agent needs.
    </Card>

    <Card title="Example task" icon="terminal">
      "Summarize open issues in actionist/catalog-test, group by label, and post the digest to #engineering on Slack." The agent calls `github:repositories:getIssues`, processes the result, then posts via the Slack connection — one prompt, two integrations.
    </Card>
  </Columns>
</div>

<div className="w-full py-10 xc-rise">
  <div className="actionist-tight flex flex-col gap-2 mb-6">
    <span className="actionist-section-eyebrow">In practice</span>
    <h2 className="text-2xl md:text-3xl font-semibold tracking-tight text-gray-900 dark:text-gray-50">Three automations teams run on day one.</h2>

    <p className="text-base text-gray-600 dark:text-gray-400 max-w-3xl">
      Real workflows built from the 33 GitHub tools above. Each fires automatically — no manual steps after the initial setup.
    </p>
  </div>

  <div className="xc-recipes">
    <div className="xc-recipe">
      <div className="xc-recipe-who">
        <i style={{background:'linear-gradient(135deg,#486EFF,#9000FF)'}} />

        Sam · Solo founder
      </div>

      <div className="xc-recipe-flow">
        When a <em>PR is opened</em>, the agent reads the diff with <em>github:pullRequests:listFiles</em>, checks for missing tests, posts a structured first-pass review comment, and requests reviewers via <em>github:pullRequests:createReview</em> — all before a human has looked at it.
      </div>

      <div className="xc-recipe-save">saves \~25 min per PR</div>
    </div>

    <div className="xc-recipe">
      <div className="xc-recipe-who">
        <i style={{background:'linear-gradient(135deg,#9000FF,#00DBFF)'}} />

        Omar · Agency owner
      </div>

      <div className="xc-recipe-flow">
        Every night at 02:00, a scheduled agent calls <em>github:repositories:getIssues</em> across 6 client repos, groups open issues by label and age, and posts a consolidated digest to Slack <em>#dev-ops</em> — 6 repos checked, one message.
      </div>

      <div className="xc-recipe-save">saves \~3 hrs/wk</div>
    </div>

    <div className="xc-recipe">
      <div className="xc-recipe-who">
        <i style={{background:'linear-gradient(135deg,#24A4FF,#6C37FF)'}} />

        Dario · Sales
      </div>

      <div className="xc-recipe-flow">
        When a new issue lands, the agent reads the title and body, matches it against the label taxonomy via <em>github:issues:listLabels</em>, applies <em>bug</em>, <em>priority:high</em>, or <em>area:\*</em> tags with <em>github:issues:update</em>, and posts a triage acknowledgment — 47 issues triaged in the first week, zero manual labels.
      </div>

      <div className="xc-recipe-save">live in 10 min</div>
    </div>
  </div>
</div>

<div className="w-full py-10 xc-rise">
  <div className="actionist-tight flex flex-col gap-2 mb-6">
    <span className="actionist-section-eyebrow">Triggers</span>
    <h2 className="text-2xl md:text-3xl font-semibold tracking-tight text-gray-900 dark:text-gray-50">Fire an agent on any GitHub event.</h2>

    <p className="text-base text-gray-600 dark:text-gray-400 max-w-3xl">
      GitHub is an <strong>App Trigger</strong> source. When a push lands, a PR opens, or an issue is created, the connected agent wakes up immediately — no polling, no hosted receiver. Pick an event below to see the pipeline in action.
    </p>
  </div>

  <div className="xagh-pipe-shell xc-try exp-tool-shell">
    <div className="mxp-srch-chips">
      <label htmlFor="xagh-ev-a"><input className="mxp-r" type="radio" name="xagh-ev" id="xagh-ev-a" defaultChecked />PR opened</label>
      <label htmlFor="xagh-ev-b"><input className="mxp-r" type="radio" name="xagh-ev" id="xagh-ev-b" />Issue created</label>
      <label htmlFor="xagh-ev-c"><input className="mxp-r" type="radio" name="xagh-ev" id="xagh-ev-c" />Push to main</label>
    </div>

    <div className="mxp-pipe" style={{marginTop:'24px'}}>
      <div className="mxp-pipe-node">
        <strong>GitHub event</strong>
        <span className="xagh-node-event-label xagh-ev-a-label">pull\_request: opened</span>
        <span className="xagh-node-event-label xagh-ev-b-label">issues: opened</span>
        <span className="xagh-node-event-label xagh-ev-c-label">push: refs/heads/main</span>
      </div>

      <div className="mxp-pipe-link" />

      <div className="mxp-pipe-node">
        <strong>App Trigger</strong>
        <span>Actionist receives the webhook payload and wakes the assigned agent.</span>
      </div>

      <div className="mxp-pipe-link d2" />

      <div className="mxp-pipe-node">
        <strong>Agent</strong>
        <span>Reads context, calls the right GitHub tools, acts on the result.</span>
      </div>

      <div className="mxp-pipe-link d3" />

      <div className="mxp-pipe-node">
        <strong>Output</strong>
        <span className="xagh-out-label xagh-out-a">First-pass review comment + reviewer request filed on the PR.</span>
        <span className="xagh-out-label xagh-out-b">Issue labeled, prioritized, and acknowledged with a triage comment.</span>
        <span className="xagh-out-label xagh-out-c">Deploy summary posted to Slack #engineering and release draft updated.</span>
      </div>
    </div>

    <div className="xagh-console-panel xagh-panel-a">
      <div className="mxp-window">
        <div className="mxp-window-bar">
          <span className="mxp-window-dot" />

          <span className="mxp-window-dot" />

          <span className="mxp-window-dot" />

          <span className="mxp-window-title">agent · pr-reviewer · trigger: pull\_request opened</span>
        </div>

        <div className="mxp-window-body" style={{minHeight:'auto',padding:'14px 18px'}}>
          <div className="mxp-stream-line"><span className="mxp-stream-time">00:00</span><span className="mxp-stream-text">Received PR #142: <em>feat/add-webhook-retry</em></span></div>
          <div style={{margin:'8px 0'}}><span className="mxp-stream-event">tool · github:pullRequests:listFiles · #142</span></div>
          <div className="mxp-stream-line"><span className="mxp-stream-time">00:01</span><span className="mxp-stream-text">12 files changed — no test file for <em>src/retry.ts</em></span></div>
          <div style={{margin:'8px 0'}}><span className="mxp-stream-event">tool · github:pullRequests:createReview · #142</span></div>
          <div className="mxp-stream-line"><span className="mxp-stream-time">00:02</span><span className="mxp-stream-text">Review posted. Requested <em>@team/backend</em> as reviewers.<span className="mxp-caret" /></span></div>
        </div>
      </div>
    </div>

    <div className="xagh-console-panel xagh-panel-b">
      <div className="mxp-window">
        <div className="mxp-window-bar">
          <span className="mxp-window-dot" />

          <span className="mxp-window-dot" />

          <span className="mxp-window-dot" />

          <span className="mxp-window-title">agent · issue-triage · trigger: issues opened</span>
        </div>

        <div className="mxp-window-body" style={{minHeight:'auto',padding:'14px 18px'}}>
          <div className="mxp-stream-line"><span className="mxp-stream-time">00:00</span><span className="mxp-stream-text">New issue #89: <em>"Search returns 500 on empty query"</em></span></div>
          <div style={{margin:'8px 0'}}><span className="mxp-stream-event">tool · github:issues:listLabels</span></div>
          <div className="mxp-stream-line"><span className="mxp-stream-time">00:01</span><span className="mxp-stream-text">Classified: <em>bug · priority:high · area:search</em></span></div>
          <div style={{margin:'8px 0'}}><span className="mxp-stream-event">tool · github:issues:update · add labels</span></div>
          <div className="mxp-stream-line"><span className="mxp-stream-time">00:02</span><span className="mxp-stream-text">Labels applied. Triage comment posted.<span className="mxp-caret" /></span></div>
        </div>
      </div>
    </div>

    <div className="xagh-console-panel xagh-panel-c">
      <div className="mxp-window">
        <div className="mxp-window-bar">
          <span className="mxp-window-dot" />

          <span className="mxp-window-dot" />

          <span className="mxp-window-dot" />

          <span className="mxp-window-title">agent · release-bot · trigger: push to main</span>
        </div>

        <div className="mxp-window-body" style={{minHeight:'auto',padding:'14px 18px'}}>
          <div className="mxp-stream-line"><span className="mxp-stream-time">00:00</span><span className="mxp-stream-text">Push landed — 3 commits since last release tag</span></div>
          <div style={{margin:'8px 0'}}><span className="mxp-stream-event">tool · github:releases:list</span></div>
          <div className="mxp-stream-line"><span className="mxp-stream-time">00:01</span><span className="mxp-stream-text">Last release: <em>v2.14.0</em> · 3 merged PRs since</span></div>
          <div style={{margin:'8px 0'}}><span className="mxp-stream-event">tool · github:releases:create · draft: v2.15.0</span></div>
          <div className="mxp-stream-line"><span className="mxp-stream-time">00:02</span><span className="mxp-stream-text">Draft created. Slack #engineering notified.<span className="mxp-caret" /></span></div>
        </div>
      </div>
    </div>
  </div>

  <div className="exp-surface-grid" style={{marginTop:'22px'}}>
    <div className="exp-surface-tile">
      <strong>No polling.</strong> The App Trigger subscribes to the GitHub webhook — your agent wakes the instant the event fires, not on the next polling interval.
    </div>

    <div className="exp-surface-tile">
      <strong>No hosted receiver.</strong> Actionist manages the callback URL and HMAC signature verification. You paste one URL into GitHub's Webhooks settings — done.
    </div>

    <div className="exp-surface-tile">
      <strong>Any event, any repo.</strong> Choose from push, PR opened/merged/closed, issue opened/labeled, release published, and more. One trigger per event type per agent.
    </div>
  </div>

  <Steps>
    <Step title="Open Reactions">
      Navigate to the agent that should respond → <strong>Reactions</strong> tab → <strong>New Trigger</strong>.
    </Step>

    <Step title="Select App Trigger">
      Choose <strong>App Trigger</strong> as the source type (subtitle: "GitHub · GitLab · installed apps"). Pick GitHub from the app selector and choose the event type.
    </Step>

    <Step title="Configure the webhook">
      A setup panel provides a callback URL and a one-time secret. Paste both into GitHub's <strong>Webhooks</strong> settings page for your repository or organization.
    </Step>
  </Steps>

  <Warning>
    The webhook setup secret is shown once. Copy it to GitHub's Webhooks settings page immediately — it cannot be retrieved after you close the panel.
  </Warning>

  <Info>
    For full details on trigger types, filter rules, and agent routing, see the <a href="/Folders/reactions">Reactions</a> page.
  </Info>
</div>

<div className="w-full py-10 xc-rise">
  <div className="actionist-tight flex flex-col gap-2 mb-6">
    <span className="actionist-section-eyebrow">Best practices</span>
    <h2 className="text-2xl md:text-3xl font-semibold tracking-tight text-gray-900 dark:text-gray-50">Tips before you go live.</h2>
  </div>

  <AccordionGroup>
    <Accordion title="PAT vs OAuth — when to use each" icon="key" defaultOpen={true}>
      OAuth grants full private repo access (`repo` scope) and is the right choice for org-wide agents. A scoped PAT stored in Credentials Vault is safer when an agent should only read public repos or a narrow subset of a private org. Store the PAT under `provider: github` and it routes automatically to every tool that needs it — no per-tool token entry.
    </Accordion>

    <Accordion title="Scope projection fallback" icon="shield">
      GitHub occasionally omits the `x-oauth-scopes` header even when the token was minted from the requested scopes. Actionist handles this automatically by falling back to the originally requested scopes for capability projection. If GitHub tools appear missing after a reconnect, disconnect and reconnect once more via the Apps detail page.
    </Accordion>

    <Accordion title="Pagination on list operations" icon="list">
      Issues, PRs, and releases default to `per_page: 50`. For repos with heavy activity, include a state filter (`state: open`) or a date range in the agent's task description. This prevents large, token-expensive payloads that slow down responses.
    </Accordion>

    <Accordion title="Credential sharing across MCPs" icon="share-2">
      Multiple MCPs that declare `provider: github` all route to the same stored credential automatically. Enter the token once in Credentials Vault and every tool — `git-official`, `github-official`, and any skill that needs `env:GITHUB_TOKEN` — is covered.
    </Accordion>

    <Accordion title="git-official vs github:* — which one to use" icon="git-branch">
      The bundled `git-official` MCP operates on local Git repositories (clone, commit, push, branch operations). The `github:*` tools call the GitHub REST API remotely (issues, PRs, releases, Actions). Use both together for a coding agent that can stage local changes and then file a PR against the remote repo.
    </Accordion>
  </AccordionGroup>
</div>

<div className="w-full py-10 xc-rise">
  <div className="actionist-cta-panel xc-border">
    <div className="relative z-10 flex flex-col items-center gap-5 max-w-2xl mx-auto">
      <span className="actionist-eyebrow">One connection</span>

      <h2 className="text-2xl md:text-3xl font-semibold tracking-tight text-white leading-tight">
        Ship faster with an agent in your repo.
      </h2>

      <p className="text-base md:text-lg text-white/85">
        Connect GitHub once. Assign the tools your agent needs. Let it triage, review, and release — while you focus on building.
      </p>

      <div className="flex flex-wrap items-center justify-center gap-3 pt-2">
        <a className="actionist-cta-btn-primary" href="https://app.actionist.ai" target="_blank" rel="noreferrer">
          Open the Dashboard

          <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.2" strokeLinecap="round" strokeLinejoin="round">
            <path d="M5 12h14" />

            <path d="m12 5 7 7-7 7" />
          </svg>
        </a>

        <a className="actionist-cta-btn-secondary" href="/Folders/reactions">
          Set up a trigger
        </a>
      </div>
    </div>
  </div>
</div>

<div className="w-full pt-2 pb-6">
  <p className="actionist-trust-line">
    33 verified GitHub tools · One OAuth connection · No webhook receiver to host.<br />
    App Triggers fire instantly on push, PR, and issue events.
  </p>
</div>

<div className="w-full pb-16">
  <div className="actionist-tight flex flex-col gap-2 mb-6">
    <span className="actionist-section-eyebrow">Keep going</span>
    <h2 className="text-2xl md:text-3xl font-semibold tracking-tight text-gray-900 dark:text-gray-50">Related topics.</h2>
  </div>

  <Columns cols={4}>
    <Card title="Credentials Vault" icon="key" href="/Folders/credentials">
      Store and rotate GitHub PATs in the encrypted vault — one entry flows to every tool that needs it.
    </Card>

    <Card title="Reactions" icon="zap" href="/Folders/reactions">
      Set up App Triggers to fire agents on push, PR-opened, and issue-created events.
    </Card>

    <Card title="Slack" icon="https://cdn.simpleicons.org/slack" href="/apps/slack">
      Route GitHub event summaries into Slack channels or DMs — the most common pairing.
    </Card>

    <Card title="Linear" icon="https://cdn.simpleicons.org/linear" href="/apps/linear">
      Bridge GitHub issues to Linear tickets for cross-tool project tracking.
    </Card>
  </Columns>
</div>