GitHub

Explore 8 actions and their permissionsExact inputs, sign-in scopes, access limits and approval rules.

With GitHub, a hire can list and read pull requests and issues, read files, check CI, comment, and open issues. There are two ways to connect it:

Either way, GitHub's side is the ceiling: a hire can never do more than the token or app allows, on more repositories than it can reach. Within that, Roster lets you narrow each hire further (see What each hire may do).

Its own GitHub identityCopy Anchor Link

Each hire gets a GitHub App of its own, named after it and your workspace (e.g. builder-acme). Its comments, issues and pushes show as builder-acme[bot], it has its own rate limit, and GitHub's audit log tells it apart from people and other hires. Roster never hands the hire a long-lived credential: it makes one-hour tokens as needed.

Before you start, add a GitHub connection under Integrations → Tools (a shared token is optional when every hire has its own identity) and give the hire GitHub on its Tools tab. For an organisation, you need to be able to create apps for it (an organisation owner, or a GitHub App manager); otherwise GitHub asks an owner to approve the install.

1. Open the hire's page, then its Tools tab, and click Give name its own GitHub identity.

   

2. Choose Where it lives: My GitHub account (for repositories you own yourself) or An organization (type its name). Continue to GitHub.
3. GitHub opens with the app filled in: its name, picture and the permissions below. Click Create GitHub App.

   Screenshot coming soonGitHub's "Create GitHub App" screen from the manifest; capture by hand on a test organisation.

4. GitHub asks where to install it. Choose Only select repositories, pick the ones this hire works on, and click Install.

   Screenshot coming soonGitHub's install screen with "Only select repositories"; capture by hand.

5. GitHub sends you back to Roster, which shows the hire's GitHub name and the repositories it can reach.

   Screenshot coming soonThe Tools tab once the hire's app is installed (e.g. builder-acme[bot] and its repositories). Needs a real GitHub App install.

If GitHub says the name is taken, use another name and try again. To add or remove repositories later, use Manage on GitHub next to the identity. Remove identity takes it away in Roster; to delete the app itself, open it on GitHub and choose Delete GitHub App.

Permissions the hire's app asks forCopy Anchor Link

The app asks for no webhooks and no organisation or account permissions.

Git, as the hireCopy Anchor Link

With its own identity, a hire can clone and push repositories it's allowed to, as itself. Inside its sandbox, Git asks Roster for a token for one repository at a time; Roster checks the hire's access and gives it a short-lived token scoped to that repository. Nothing long-lived ever reaches the sandbox. Commits are authored by the hire's bot.

A shared tokenCopy Anchor Link

The quick way: one token for the workspace. Every hire using it shows on GitHub as the token's owner and shares its rate limit (5,000 requests an hour).

1. Make a fine-grained token on GitHubCopy Anchor Link

1. Open GitHub's new fine-grained token page, filled in for Roster (the form in Roster links there too). The name and the permissions in the table below are already set.
2. Expiration: as long as your policy allows; you'll paste a new one when it expires.
3. Resource owner: your organisation (it may need an owner to approve the token).
4. Repository access: Only select repositories, then pick the ones hires work on.
5. Permissions: check they match the table below, and nothing else.
6. Click Generate token and copy it (it starts with github_pat_, or ghp_ for a classic token). Roster tells you at once if what you paste doesn't look like a GitHub token.

Prefer read only? Give Issues and Pull requests Read only; hires then can't comment or open issues, and they'll say so instead.

2. Add it to RosterCopy Anchor Link

1. Open Integrations → Tools and click Add a tool, then GitHub.
2. Paste the token into Access token. Leave API address empty unless you use GitHub Enterprise Server (then it's https://github.example.com/api/v3).
3. Click Connect. Roster asks GitHub who the token belongs to, and the connection shows Connected as that GitHub user. If GitHub refuses the token, Roster says so and saves nothing.

Roster seals the token and never shows it again. To replace it, click Change on the connection.

What each hire may doCopy Anchor Link

On the hire's Tools tab, add GitHub (or click Change access on it) and choose:

• Repositories: owner/name, one per line. The hire can only use these, checked on every call. Empty means every repository the token or app can reach.
• What they can do: Read only (list and read; it can't comment, open issues or push) or Read and write.

A hire refused something gets a plain error and tells the person who asked.

What hires can do with GitHubCopy Anchor Link

A responsibility can also watch GitHub: Roster checks for updated issues and pull requests on its own, off the clock, and wakes the hire only when something changed (see Responsibilities).

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "repo": {
      "type": "string",
      "pattern": "^(?!\\.{1,2}\\/)[\\w.-]+\\/(?!\\.{1,2}$)[\\w.-]+$",
      "description": "owner/name"
    },
    "state": {
      "default": "open",
      "type": "string",
      "enum": [
        "open",
        "closed",
        "all"
      ]
    }
  },
  "required": [
    "repo"
  ]
}

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "repo": {
      "type": "string",
      "pattern": "^(?!\\.{1,2}\\/)[\\w.-]+\\/(?!\\.{1,2}$)[\\w.-]+$",
      "description": "owner/name"
    },
    "number": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "repo",
    "number"
  ]
}

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "repo": {
      "type": "string",
      "pattern": "^(?!\\.{1,2}\\/)[\\w.-]+\\/(?!\\.{1,2}$)[\\w.-]+$",
      "description": "owner/name"
    },
    "state": {
      "default": "open",
      "type": "string",
      "enum": [
        "open",
        "closed",
        "all"
      ]
    },
    "labels": {
      "description": "comma-separated",
      "type": "string"
    }
  },
  "required": [
    "repo"
  ]
}

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "repo": {
      "type": "string",
      "pattern": "^(?!\\.{1,2}\\/)[\\w.-]+\\/(?!\\.{1,2}$)[\\w.-]+$",
      "description": "owner/name"
    },
    "number": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "repo",
    "number"
  ]
}

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "repo": {
      "type": "string",
      "pattern": "^(?!\\.{1,2}\\/)[\\w.-]+\\/(?!\\.{1,2}$)[\\w.-]+$",
      "description": "owner/name"
    },
    "path": {
      "type": "string",
      "minLength": 1
    },
    "ref": {
      "type": "string"
    }
  },
  "required": [
    "repo",
    "path"
  ]
}

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "repo": {
      "type": "string",
      "pattern": "^(?!\\.{1,2}\\/)[\\w.-]+\\/(?!\\.{1,2}$)[\\w.-]+$",
      "description": "owner/name"
    },
    "branch": {
      "type": "string"
    },
    "status": {
      "type": "string"
    }
  },
  "required": [
    "repo"
  ]
}

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "repo": {
      "type": "string",
      "pattern": "^(?!\\.{1,2}\\/)[\\w.-]+\\/(?!\\.{1,2}$)[\\w.-]+$",
      "description": "owner/name"
    },
    "number": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "body": {
      "type": "string",
      "minLength": 1
    }
  },
  "required": [
    "repo",
    "number",
    "body"
  ]
}

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "repo": {
      "type": "string",
      "pattern": "^(?!\\.{1,2}\\/)[\\w.-]+\\/(?!\\.{1,2}$)[\\w.-]+$",
      "description": "owner/name"
    },
    "title": {
      "type": "string",
      "minLength": 1
    },
    "body": {
      "default": "",
      "type": "string"
    },
    "labels": {
      "default": [],
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "repo",
    "title"
  ]
}