Probot usesGitHub Apps for authorizing requests to GitHub's APIs. A registered GitHub App is a first-class actor on GitHub, like a user (e.g.@bkeepers) or an organization (e.g.@github). The GitHub App is granted access to all or selected repositories by being "installed" on a user or organization account and can perform actions through the API likecommenting on an issue orcreating a status.
Your Probot app has access to an authenticatedOctokit client that can be used to make API calls. It supports both theGitHub REST API, and theGitHub GraphQL API.
context.octokit is an instance of the@octokit/rest Node.js module, and allows you to do almost anything programmatically that you can do through a web browser.
Here is an example of an autoresponder app that comments on opened issues:
exportdefault(app)=>{ app.on("issues.opened",async(context)=>{// `context` extracts information from the event, which can be passed to// GitHub API calls. This will return:// { owner: 'yourname', repo: 'yourrepo', number: 123, body: 'Hello World! }const params= context.issue({body:"Hello World!"});// Post a comment on the issuereturn context.octokit.issues.createComment(params);});};See thefull API docs to see all the ways you can interact with GitHub. Some API endpoints are not available on GitHub Apps yet, so checkwhich ones are available first.
Usecontext.octokit.graphql to make requests to theGitHub GraphQL API.
Here is an example of the same autoresponder app from above that comments on opened issues, but this time with GraphQL:
// GraphQL query to add a commentconst addComment=` mutation comment($id: ID!, $body: String!) { addComment(input: {subjectId: $id, body: $body}) { clientMutationId } }`;exportdefault(app)=>{ app.on("issues.opened",async(context)=>{// Post a comment on the issue context.octokit.graphql(addComment,{id: context.payload.issue.node_id,body:"Hello World",});});};The options in the 2nd argument will be passed as variables to the query. You can pass custom headers by using theheaders key:
// GraphQL query to pin an issueconst pinIssue=` mutation comment($id: ID!) { pinIssue(input: {subjectId: $id}) { clientMutationId } }`;exportdefault(app)=>{ app.on("issues.opened",async(context)=>{ context.octokit.graphql(pinIssue,{id: context.payload.issue.node_id,headers:{accept:"application/vnd.github.elektra-preview+json",},});});};Check out theGitHub GraphQL API docs to learn more.
Whenreceiving webhook events,context.octokit isusually an authenticated client, but there are a few events that are exceptions:
installation.deleted &installation.suspend - The installation wasjust deleted or suspended, so we can't authenticate as the installation.
marketplace_purchase - The purchase happens before the app is installed on an account.
For these events,context.octokit will be unauthenticated. Attemts to send any requests will fail with an error explaining the circumstances.
If you want to run a Probot App against a GitHub Enterprise instance, you'll need to create and set theGHE_HOST environment variable inside of the.env file.
GHE_HOST=fake.github-enterprise.comWhenusing Probot programmatically, set thebaseUrl option for theProbot constructor to the full base Url of the REST API
const MyProbot= Probot.defaults({baseUrl:"https://fake.github-enterprise.com/api/v3",});Found a mistake or want to help improve this documentation?Suggest changes on GitHub