# Automatic Refresh

Use /install-wiki to set up a CI action that regenerates a Wiki on every push to the default branch.

The `/install-wiki` command creates a CI workflow that automatically regenerates a Wiki every time code is pushed to the default branch. It detects your CI framework (GitHub Actions or GitLab CI) and generates the appropriate configuration. This keeps your documentation in sync with your codebase without manual intervention.

## Quick start

<Steps>
  <Step title="Open a Droid session in your repo">
    ```bash
    cd /path/to/your/project
    droid
    ```
  </Step>
  <Step title="Run the install command">
    ```
    > /install-wiki
    ```
    Droid creates a workflow file and opens a pull request for you to review.
  </Step>
  <Step title="Add the Factory API key">
    Add `FACTORY_API_KEY` as a secret in your CI settings:
    - **GitHub**: Repository **Settings > Secrets and variables > Actions** (or at the organization level under **Organization Settings > Secrets and variables > Actions**)
    - **GitLab**: Repository **Settings > CI/CD > Variables** (or at the group level under **Group Settings > CI/CD > Variables**)

    Generate a key in the <a href="https://app.factory.ai/settings/api-keys">Factory API keys settings</a>.
  </Step>
  <Step title="Merge the PR">
    Once the secret is configured, merge the workflow PR. The Wiki will now
    refresh automatically on every push to the default branch.
  </Step>
</Steps>

## Generated workflows

Droid detects your CI framework and creates the appropriate configuration.

### GitHub Actions

Creates `.github/workflows/droid-wiki-refresh.yml` (replace `main` with your default branch if different):

```yaml
name: Droid AutoWiki Refresh

on:
  push:
    branches: [main] # change to your default branch if not main

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

      - name: Install Factory Droid
        run: curl -fsSL https://app.factory.ai/cli | sh

      - name: Generate Wiki
        run: droid exec --auto high "/wiki"
        env:
          FACTORY_API_KEY: ${{ secrets.FACTORY_API_KEY }}
```

### GitLab CI

Appends a job to your existing `.gitlab-ci.yml`:

```yaml
droid-wiki-refresh:
  stage: deploy
  before_script:
    - curl -fsSL https://app.factory.ai/cli | sh
  script:
    - droid exec --auto high "/wiki"
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  variables:
    FACTORY_API_KEY: $FACTORY_API_KEY
```

Both workflows:

{/* sweep-allow: term-bullets */}

- **Trigger on push** to the default branch
- **Install the Droid CLI** using the official installer
- **Run `/wiki`** in headless mode with high autonomy, generating the Wiki and storing it in the Factory App with Cloud Sync

<Tip>
  You can customize the workflow after installation. For example, change the
  trigger branch, add path filters to only regenerate when source files change,
  or adjust the timeout.
</Tip>

## Prerequisites

- A GitHub or GitLab hosted repository
- A Factory API key (generate one in the <a href="https://app.factory.ai/settings/api-keys">Factory API keys settings</a>)
- Permission to add secrets and merge PRs in the target repository

## Refreshing from the Factory App

You can also set up recurring refreshes from the Factory App:

1. Go to <a href="https://app.factory.ai/wiki">app.factory.ai/wiki</a>
2. Click **Refresh** on the Wiki page
3. Select **Recurring (on push)**
4. Choose a **Local** or **Cloud** method:
   - **Local**: Copies the `/install-wiki` command for you to run in a local clone
   - **Cloud**: Selects a cloud template or Droid Computer to run the setup remotely

For batch operations across multiple repositories, the Factory App lets you select several repos and run the setup on a Droid Computer in a single operation.

See [Wiki Browser](/software-factory/wiki/web-viewer) for more on the Factory App interface.

## Troubleshooting

<Troubleshooting>
  <TroubleshootingItem title="Workflow fails with authentication error">
    Verify the `FACTORY_API_KEY` secret is set correctly in your repository's
    **Settings > Secrets and variables > Actions**. Generate a new key at
    <a href="https://app.factory.ai/settings/api-keys">Factory API keys settings</a>
    if needed.
  </TroubleshootingItem>

  <TroubleshootingItem title="AutoWiki is not updating after push">
    Check that the workflow file exists at `.github/workflows/droid-wiki-refresh.yml`
    and that the branch trigger matches your default branch. View the Actions
    tab in your repository to see workflow run logs.
  </TroubleshootingItem>

  <TroubleshootingItem title="GitHub Wiki is not syncing">
    The GitHub Wiki tab must be initialized before Factory can push to it. Create
    the first page manually at `https://github.com/{owner}/{repo}/wiki`. Also
    verify that your organization hasn't disabled
    [AutoWiki Cloud Sync](/software-factory/wiki/overview#autowiki-cloud-sync).
  </TroubleshootingItem>
</Troubleshooting>

<RelatedLinks>
  <RelatedLink href='/droid-exec/overview' title='Droid Exec'>
    Headless mode used by the generated workflow.
  </RelatedLink>
  <RelatedLink href='/software-factory/wiki/overview' title='AutoWiki Overview'>
    How Factory generates and publishes repository documentation.
  </RelatedLink>
</RelatedLinks>