mirror of
https://github.com/actions/toolkit.git
synced 2025-06-10 10:00:45 +09:00
Add github context getting started docs (#80)
* WIP - Add github context getting started docs * Add testing docs * Update walkthrough after going through it * Clean up * Add markdown types * Env disclaimer * Fix broken link to Javascript Action (#103)
This commit is contained in:
Danny McCormick
parent
ef4525e9dd
commit
3dcd65e44b
GPG key ID:
4AEE18F83AFDEB23
4 changed files with 367 additions and 78 deletions
100
docs/specs/github-package.md
Normal file
100
docs/specs/github-package.md
Normal file
|
|
@ -0,0 +1,100 @@
|
|||
# Github Package
|
||||
|
||||
In order to support using actions to interact with GitHub, I propose adding a `github` package to the toolkit.
|
||||
|
||||
Its main purpose will be to provide a hydrated GitHub context/Octokit client with some convenience functions. It is largely pulled from the GitHub utilities provided in https://github.com/JasonEtco/actions-toolkit, though it has been condensed.
|
||||
|
||||
### Spec
|
||||
|
||||
##### interfaces.ts
|
||||
|
||||
```ts
|
||||
/*
|
||||
* Interfaces
|
||||
*/
|
||||
|
||||
export interface PayloadRepository {
|
||||
[key: string]: any
|
||||
full_name?: string
|
||||
name: string
|
||||
owner: {
|
||||
[key: string]: any
|
||||
login: string
|
||||
name?: string
|
||||
}
|
||||
html_url?: string
|
||||
}
|
||||
|
||||
export interface WebhookPayloadWithRepository {
|
||||
[key: string]: any
|
||||
repository?: PayloadRepository
|
||||
issue?: {
|
||||
[key: string]: any
|
||||
number: number
|
||||
html_url?: string
|
||||
body?: string
|
||||
}
|
||||
pull_request?: {
|
||||
[key: string]: any
|
||||
number: number
|
||||
html_url?: string
|
||||
body?: string
|
||||
}
|
||||
sender?: {
|
||||
[key: string]: any
|
||||
type: string
|
||||
}
|
||||
action?: string
|
||||
installation?: {
|
||||
id: number
|
||||
[key: string]: any
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
##### context.ts
|
||||
|
||||
Contains a GitHub context
|
||||
|
||||
```ts
|
||||
export class Context {
|
||||
/**
|
||||
* Webhook payload object that triggered the workflow
|
||||
*/
|
||||
public payload: WebhookPayloadWithRepository
|
||||
|
||||
/**
|
||||
* Name of the event that triggered the workflow
|
||||
*/
|
||||
public event: string
|
||||
public sha: string
|
||||
public ref: string
|
||||
public workflow: string
|
||||
public action: string
|
||||
public actor: string
|
||||
|
||||
/**
|
||||
* Hydrate the context from the environment
|
||||
*/
|
||||
constructor ()
|
||||
|
||||
public get issue ()
|
||||
|
||||
public get repo ()
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
##### github.ts
|
||||
|
||||
Contains a hydrated Octokit client
|
||||
|
||||
```ts
|
||||
export class GithubClient extends Octokit {
|
||||
// For making GraphQL requests
|
||||
public graphql: (query: string, variables?: Variables) => Promise<GraphQlQueryResponse>
|
||||
|
||||
// Calls super and initializes graphql
|
||||
constructor (token: string)
|
||||
}
|
||||
```
|
||||
203
docs/specs/package-specs.md
Normal file
203
docs/specs/package-specs.md
Normal file
|
|
@ -0,0 +1,203 @@
|
|||
# Package Specs
|
||||
|
||||
In order to support the node-config action, I propose adding the following into 4 libraries (tool-cache, core, io, exec), with tool-cache having dependencies on the other 3 libs:
|
||||
|
||||
### Core spec
|
||||
|
||||
Holds all the functions necessary for interacting with the runner/environment.
|
||||
|
||||
```ts
|
||||
// Logging functions
|
||||
export function debug(message: string): void
|
||||
export function warning(message: string): void
|
||||
export function error(message: string): void
|
||||
|
||||
/**
|
||||
* sets env variable for this action and future actions in the job
|
||||
* @param name the name of the variable to set
|
||||
* @param val the value of the variable
|
||||
*/
|
||||
export function exportVariable(name: string, val: string): void
|
||||
|
||||
/**
|
||||
* exports the variable and registers a secret which will get masked from logs
|
||||
* @param name the name of the variable to set
|
||||
* @param val value of the secret
|
||||
*/
|
||||
export function exportSecret(name: string, val: string): void
|
||||
|
||||
/**
|
||||
* Prepends inputPath to the PATH
|
||||
* @param inputPath
|
||||
*/
|
||||
export function addPath(inputPath: string): void
|
||||
|
||||
/**
|
||||
* Interface for getInput options
|
||||
*/
|
||||
export interface InputOptions {
|
||||
/** Optional. Whether the input is required. If required and not present, will throw. Defaults to false */
|
||||
required?: bool;
|
||||
}
|
||||
|
||||
/**
|
||||
* Gets the value of an input. The value is also trimmed.
|
||||
*
|
||||
* @param name name of the input to get
|
||||
* @param options optional. See InputOptions.
|
||||
* @returns string
|
||||
*/
|
||||
export function getInput(name: string, options?: InputOptions): string | undefined
|
||||
|
||||
/**
|
||||
* sets the status of the action to neutral
|
||||
* @param message
|
||||
*/
|
||||
export function setNeutral(message: string): void
|
||||
|
||||
/**
|
||||
* sets the status of the action to failed
|
||||
* @param message
|
||||
*/
|
||||
export function setFailed(message: string): void
|
||||
```
|
||||
|
||||
### IO spec
|
||||
|
||||
Holds all the functions necessary for file system manipulation (cli scenarios, not fs replacements):
|
||||
|
||||
```ts
|
||||
/**
|
||||
* Interface for cp/mv options
|
||||
*/
|
||||
export interface CopyOptions {
|
||||
/** Optional. Whether to recursively copy all subdirectories. Defaults to false */
|
||||
recursive?: boolean;
|
||||
/** Optional. Whether to overwrite existing files in the destination. Defaults to true */
|
||||
force?: boolean;
|
||||
}
|
||||
|
||||
/**
|
||||
* Copies a file or folder.
|
||||
*
|
||||
* @param source source path
|
||||
* @param dest destination path
|
||||
* @param options optional. See CopyOptions.
|
||||
*/
|
||||
export function cp(source: string, dest: string, options?: CopyOptions): Promise<void>
|
||||
|
||||
/**
|
||||
* Remove a path recursively with force
|
||||
*
|
||||
* @param path path to remove
|
||||
*/
|
||||
export function rmRF(path: string): Promise<void>
|
||||
|
||||
/**
|
||||
* Make a directory. Creates the full path with folders in between
|
||||
*
|
||||
* @param p path to create
|
||||
* @returns Promise<void>
|
||||
*/
|
||||
export function mkdirP(p: string): Promise<void>
|
||||
|
||||
/**
|
||||
* Moves a path.
|
||||
*
|
||||
* @param source source path
|
||||
* @param dest destination path
|
||||
* @param options optional. See CopyOptions.
|
||||
*/
|
||||
export function mv(source: string, dest: string, options?: CopyOptions): Promise<void>
|
||||
|
||||
/**
|
||||
* Interface for which options
|
||||
*/
|
||||
export interface WhichOptions {
|
||||
/** Optional. Whether to check if tool exists. If true, will throw if it fails. Defaults to false */
|
||||
check?: boolean;
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns path of a tool had the tool actually been invoked. Resolves via paths.
|
||||
*
|
||||
* @param tool name of the tool
|
||||
* @param options optional. See WhichOptions.
|
||||
* @returns Promise<string> path to tool
|
||||
*/
|
||||
export function which(tool: string, options?: WhichOptions): Promise<string>
|
||||
```
|
||||
|
||||
### Exec spec
|
||||
|
||||
Holds all the functions necessary for running the tools node-config depends on (aka 7-zip and tar)
|
||||
|
||||
```ts
|
||||
/**
|
||||
* Interface for exec options
|
||||
*/
|
||||
export interface IExecOptions
|
||||
|
||||
/**
|
||||
* Exec a command.
|
||||
* Output will be streamed to the live console.
|
||||
* Returns promise with return code
|
||||
*
|
||||
* @param commandLine command to execute
|
||||
* @param args optional additional arguments
|
||||
* @param options optional exec options. See IExecOptions
|
||||
* @returns Promise<number> return code
|
||||
*/
|
||||
export function exec(commandLine: string, args?: string[], options?: IExecOptions): Promise<number>
|
||||
```
|
||||
|
||||
### Tool-Cache spec:
|
||||
|
||||
Holds all the functions necessary for downloading and caching node.
|
||||
|
||||
```ts
|
||||
/**
|
||||
* Download a tool from an url and stream it into a file
|
||||
*
|
||||
* @param url url of tool to download
|
||||
* @returns path to downloaded tool
|
||||
*/
|
||||
export async function downloadTool(url: string): Promise<string>
|
||||
|
||||
/**
|
||||
* Extract a .7z file
|
||||
*
|
||||
* @param file path to the .7z file
|
||||
* @param dest destination directory. Optional.
|
||||
* @returns path to the destination directory
|
||||
*/
|
||||
export async function extract7z(file: string, dest?: string): Promise<string>
|
||||
|
||||
/**
|
||||
* Extract a tar
|
||||
*
|
||||
* @param file path to the tar
|
||||
* @param dest destination directory. Optional.
|
||||
* @returns path to the destination directory
|
||||
*/
|
||||
export async function extractTar(file: string, destination?: string): Promise<string>
|
||||
|
||||
/**
|
||||
* Caches a directory and installs it into the tool cacheDir
|
||||
*
|
||||
* @param sourceDir the directory to cache into tools
|
||||
* @param tool tool name
|
||||
* @param version version of the tool. semver format
|
||||
* @param arch architecture of the tool. Optional. Defaults to machine architecture
|
||||
*/
|
||||
export async function cacheDir(sourceDir: string, tool: string, version: string, arch?: string): Promise<string>
|
||||
|
||||
/**
|
||||
* finds the path to a tool in the local installed tool cache
|
||||
*
|
||||
* @param toolName name of the tool
|
||||
* @param versionSpec version of the tool
|
||||
* @param arch optional arch. defaults to arch of computer
|
||||
*/
|
||||
export function find(toolName: string, versionSpec: string, arch?: string): string
|
||||
```
|
||||
Loading…
Add table
Add a link
Reference in a new issue