← All integrations

Guide

Start a run from GitHub Actions

Add one step to your workflow and every push starts an OKShip run on your app. If OKShip refuses the run, the job fails and the log says why.

Before you start

  • Your own Anthropic key, saved and verified in Settings, under Bring your own Anthropic key (BYOK). Runs started from GitHub use your key, so OKShip won't start them without one.
  • An owner of your team in OKShip. Only owners can turn on GitHub Actions and make API keys.
  • A GitHub repository where you can add a workflow and a repository secret.
  • An app in OKShip with at least one goal saved.

Set it up

  1. 1. Turn on GitHub Actions in OKShip

    In Settings, find the section called GitHub Actions and select Activate GitHub Actions. The button stays off until your Anthropic key is verified.

  2. 2. Make an API key that can start runs

    In Settings, under API keys, give the key a name. Under What can this key do?, choose Start runs, then select Create key.

    OKShip shows the key once. Copy it now; you can't see it again.

    Settings, API keys: the new-key form with Start runs chosen
  3. 3. Add the key to GitHub

    In your GitHub repository's settings, add a repository secret named OKSHIP_API_KEY and paste the key as its value.

    GitHub, a repository's Actions secrets page with OKSHIP_API_KEY added (no value visible)
  4. 4. Find your app's ID

    Open the app in OKShip. Its ID is the last part of the page address, after /dashboard/apps/.

  5. 5. Add the workflow

    Create the file .github/workflows/okship.yml in your repository and paste this in. Replace <your-app-uuid> with your app's ID.

    name: OKShip CI run
    on: [push]
    jobs:
      okship:
        runs-on: ubuntu-latest
        steps:
          - name: Trigger OKShip run
            run: |
              curl --fail-with-body -X POST https://okship.dev/api/runs \
                -H "X-API-Key: ${{ secrets.OKSHIP_API_KEY }}" \
                -H "Content-Type: application/json" \
                -d '{"app_id": "<your-app-uuid>"}'

    Settings shows the same workflow, with a Copy button, once GitHub Actions is on.

    Settings, the GitHub Actions section after turning it on: Connected badge, the workflow with its Copy button

After you push

Each push to the repository starts a run that checks every goal saved on the app.

The step finishes as soon as OKShip accepts the run. It doesn't wait for the verdict, so a green job means the run started, not that the goals passed. The job log shows OKShip's reply, including the run's ID.

The results arrive the way all your runs do: on the run's page in OKShip, and in Slack if you've connected it.

Runs started from GitHub count toward your plan like any other run.

A workflow run in GitHub Actions: the job that starts the OKShip run, passing.

When a run is refused

When OKShip refuses a run, it starts nothing and it isn't counted. The job fails, and the log shows a code and a message.

CodeWhat the log saysWhat to do
byok_requiredRuns started with an API key use your own Anthropic key. Add one in Settings, under Bring your own Anthropic key (BYOK), then connect GitHub Actions.Save your Anthropic key, then turn on GitHub Actions.
byok_requiredRuns started with an API key use your own Anthropic key, and yours isn't currently verified. Re-save it in Settings, under Bring your own Anthropic key (BYOK).Save your Anthropic key again so OKShip can check it.
github_actions_not_connectedRuns started with an API key need GitHub Actions connected. An owner can activate it in Settings, under GitHub Actions.Ask an owner to turn GitHub Actions back on.

Other replies you might see:

  • invalid_api_key: The secret doesn't match a working key. Check the secret's value, or make a new key if the old one was revoked.
  • insufficient_scope: The key can't start runs. Make a key with Start runs chosen.
  • api_key_creator_not_member, insufficient_role: The key acts for the person who made it. If they've left the team or can no longer start runs, make a new key.
  • Your plan's limit is reached. The message says which limit.

Disconnect

To stop runs from GitHub, select Disconnect in the GitHub Actions section. OKShip asks first:

Disconnect GitHub Actions? Existing API keys remain valid but your workflow will start failing until you reactivate.

After that, every run your workflow tries is refused and the job fails, until an owner turns it back on. Your API keys aren't revoked.

If your Anthropic key is removed, OKShip turns GitHub Actions off for you. Save a key, then turn it back on.

Security

See it on your own site

Point OKShip at your site, write what a user should be able to do, and get a report and a link you can send.

Try it for free