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

# GitHub Integration

> Connect GitHub for automatic deployments on every push.

Connecting GitHub to your Nometria project means your app redeploys automatically every time you push to your repo. No manual deploys needed -- just push your code and it goes live.

## Connect GitHub

<Steps>
  <Step title="Run the connect command">
    ```bash theme={null}
    nom github connect
    ```

    This opens your browser to authorize Nometria to access your GitHub account via OAuth.
  </Step>

  <Step title="Authorize in the browser">
    Sign in to GitHub (if you are not already) and approve the authorization. The browser redirects back to your terminal automatically.
  </Step>

  <Step title="Verify the connection">
    ```bash theme={null}
    nom github status
    ```

    **Example output:**

    ```
      GitHub connected as octocat
    ```
  </Step>
</Steps>

## Auto-deploy on push

Once GitHub is connected, every push to your default branch (usually `main`) triggers a new deployment automatically. The flow looks like this:

1. You push code to GitHub
2. Nometria detects the push via webhook
3. Your app is rebuilt and redeployed
4. The new version is live in about 2 minutes

<Info>
  Only pushes to the branch configured in your Nometria project trigger deploys. Pushes to other branches are ignored unless you configure them in the dashboard.
</Info>

## Push changes from the CLI

If you want to commit and push in one step, the CLI has a shortcut:

```bash theme={null}
nom github push -m "Add new feature"
```

This stages your changes, creates a commit with the message you provide, and pushes to the connected repo. If auto-deploy is enabled, a new deployment starts immediately.

<Tip>
  This is especially useful when an AI coding tool makes changes to your project. Instead of switching to git manually, just run one command.
</Tip>

## List connected repos

See which repos are linked to your account:

```bash theme={null}
nom github repos
```

**Example output:**

```
  octocat/my-app (TypeScript) [private]
  octocat/landing-page (JavaScript)
```

## GitHub Actions workflow

For more control over the deployment process, you can use a GitHub Actions workflow instead of (or in addition to) the webhook-based auto-deploy.

Run `nom setup` to generate the workflow file automatically:

```bash theme={null}
nom setup
```

This creates `.github/workflows/nometria-deploy.yml`:

```yaml theme={null}
name: Deploy to Nometria

on:
  push:
    branches: [main]
  workflow_dispatch:

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dependencies
        run: npm ci

      - name: Deploy
        run: npx @nometria-ai/nom deploy --yes
        env:
          NOMETRIA_API_KEY: ${{ secrets.NOMETRIA_API_KEY }}
```

### Set up the secret

<Steps>
  <Step title="Get your API key">
    Go to [nometria.com/settings/api-keys](https://nometria.com/settings/api-keys) and generate a key (or copy an existing one).
  </Step>

  <Step title="Add it to GitHub">
    In your GitHub repo, go to **Settings > Secrets and variables > Actions** and create a new secret called `NOMETRIA_API_KEY` with your key as the value.
  </Step>

  <Step title="Push the workflow">
    Commit and push the `.github/workflows/nometria-deploy.yml` file. The next push to `main` will trigger the workflow.
  </Step>
</Steps>

### Manual deploys

The workflow includes `workflow_dispatch`, which means you can also trigger it manually from the **Actions** tab in GitHub. This is useful when you want to redeploy without pushing new code.

<Warning>
  If you use both webhook auto-deploy and GitHub Actions, you may get duplicate deployments. Pick one approach. The GitHub Actions method gives you more control (you can add tests, linting, etc. before the deploy step).
</Warning>

## Troubleshooting

<AccordionGroup>
  <Accordion title="GitHub connect opens the browser but nothing happens">
    Make sure you are signed in to your Nometria account first:

    ```bash theme={null}
    nom login
    ```

    Then try `nom github connect` again.
  </Accordion>

  <Accordion title="Pushes are not triggering deploys">
    Check that the connection is active:

    ```bash theme={null}
    nom github status
    ```

    If it says "not connected", run `nom github connect` again. Also verify you are pushing to the correct branch.
  </Accordion>

  <Accordion title="GitHub Actions workflow fails">
    Check that the `NOMETRIA_API_KEY` secret is set correctly in your repo settings. You can also add `NOM_DEBUG=1` to the env block to get more detailed output:

    ```yaml theme={null}
    env:
      NOMETRIA_API_KEY: ${{ secrets.NOMETRIA_API_KEY }}
      NOM_DEBUG: 1
    ```
  </Accordion>
</AccordionGroup>