Package me.julb.sdk.github.actions.kit

Class GitHubActionsKit

java.lang.Object
me.julb.sdk.github.actions.kit.GitHubActionsKit
public class GitHubActionsKit extends Object
Kit methods for GitHub actions.
Author:
Julb.

  • Field Details

    • INSTANCE

      public static final GitHubActionsKit INSTANCE
      The public instance to use.

  • Constructor Details

    • GitHubActionsKit

      public GitHubActionsKit()

  • Method Details

    • getInput

      public Optional<String> getInput(@NonNull @NonNull String name)
      Gets the input with the given name.
      Parameters:
      name - the input name.
      Returns:
      the input value trimmed, or empty if input is not provided.

    • getInput

      public Optional<String> getInput(@NonNull @NonNull String name, boolean trimValue)
      Gets the input with the given name, with the option to trim the value.
      Parameters:
      name - the input name.
      trimValue - true to trim the input value, false to let as-is.
      Returns:
      the input value or empty if input is not provided.

    • getRequiredInput

      public String getRequiredInput(@NonNull @NonNull String name)
      Gets the input with the given name.
      This method throws a NoSuchElementException if the input does not exist.
      Parameters:
      name - the input name.
      Returns:
      the input value.
      Throws:
      NoSuchElementException - if the object does not exist.

    • getRequiredInput

      public String getRequiredInput(@NonNull @NonNull String name, boolean trimValue)
      Gets the input with the given name.
      This method throws a NoSuchElementException if the input does not exist.
      Parameters:
      name - the input name.
      trimValue - true to trim the input value, false to let as-is.
      Returns:
      the input value or empty if input is not provided.
      Throws:
      NoSuchElementException - if the object does not exist.

    • getBooleanInput

      public Optional<Boolean> getBooleanInput(@NonNull @NonNull String name)
      Gets the boolean input with the given name.
      Parameters:
      name - the input name.
      Returns:
      the input value trimmed, or empty if input is not provided.
      Throws:
      IllegalArgumentException - if the value is not a valid boolean value.

    • getRequiredBooleanInput

      public Boolean getRequiredBooleanInput(@NonNull @NonNull String name)
      Gets the boolean input with the given name.
      This method throws a NoSuchElementException if the input does not exist.
      Parameters:
      name - the input name.
      Returns:
      the input value.
      Throws:
      NoSuchElementException - if the object does not exist.
      IllegalArgumentException - if the value is not a valid boolean value.

    • getEnumInput

      public <T extends Enum<T>> Optional<T> getEnumInput(@NonNull @NonNull String name, Class<T> enumClass)
      Gets the input value with the given name as an Enum.
      Type Parameters:
      T - the enum object type.
      Parameters:
      name - the input name.
      enumClass - the enum class.
      Returns:
      the input value as an enum, or empty if input is not provided.
      Throws:
      IllegalArgumentException - if the value is not a valid enum value.

    • getRequiredEnumInput

      public <T extends Enum<T>> T getRequiredEnumInput(@NonNull @NonNull String name, Class<T> enumClass)
      Gets the enum input value with the given name as an Enum.
      This method throws a NoSuchElementException if the input does not exist.
      Type Parameters:
      T - the enum object type.
      Parameters:
      name - the input name.
      enumClass - the enum class.
      Returns:
      the input value as an enum, or empty if input is not provided.
      Throws:
      NoSuchElementException - if the object does not exist.
      IllegalArgumentException - if the value is not a valid enum value.

    • getMultilineInput

      public Optional<String[]> getMultilineInput(@NonNull @NonNull String name)
      Gets the multiline input with the given name.
      Each value is trimmed and blank values are not returned.
      Parameters:
      name - the input name.
      Returns:
      the multiline input value as an array, or empty if input is not provided.

    • getMultilineInput

      public Optional<String[]> getMultilineInput(@NonNull @NonNull String name, boolean trimValue)
      Gets the multiline input with the given name.
      Blank values are not returned.
      Parameters:
      name - the input name.
      trimValue - true to trim the input value, false to let as-is.
      Returns:
      the multiline input value as an array, or empty if input is not provided.

    • getRequiredMultilineInput

      public String[] getRequiredMultilineInput(@NonNull @NonNull String name)
      Gets the multiline input with the given name.

      This method throws a NoSuchElementException if the input does not exist.
      Each value is trimmed and blank values are not returned.
      Parameters:
      name - the input name.
      Returns:
      the multiline input value as an array.
      Throws:
      NoSuchElementException - if the object does not exist.

    • getRequiredMultilineInput

      public String[] getRequiredMultilineInput(@NonNull @NonNull String name, boolean trimValue)
      Gets the multiline input with the given name.

      This method throws a NoSuchElementException if the input does not exist.
      Blank values are not returned.
      Parameters:
      name - the input name.
      trimValue - true to trim the input value, false to let as-is.
      Returns:
      the multiline input value as an array.
      Throws:
      NoSuchElementException - if the object does not exist.

    • setOutput

      public <T> void setOutput(@NonNull @NonNull String name, @NonNull T value)
      Sets the given output variable.
      Type Parameters:
      T - the output object type.
      Parameters:
      name - the output variable name.
      value - the output variable value.

    • setOptionalOutput

      public <T> void setOptionalOutput(@NonNull @NonNull String name, @NonNull @NonNull Optional<T> value)
      Sets the given output variable.
      Type Parameters:
      T - the output object type.
      Parameters:
      name - the output variable name.
      value - the output variable value.

    • setEmptyOutput

      public void setEmptyOutput(@NonNull @NonNull String name)
      Sets the given output variable with an empty value.
      Parameters:
      name - the output variable name.

    • setCommandEcho

      public void setCommandEcho(boolean enabled)
      Enables or disables the echoing of commands into STDOUT for the rest of the step.
      Echoing is disabled by default if ACTIONS_STEP_DEBUG is not set.
      Parameters:
      enabled - true to enable, false otherwise.

    • startGroup

      public void startGroup(@NonNull @NonNull String name)
      Starts a group with the given name.
      Output until the call to endGroup() will be foldable.
      Parameters:
      name - the name of the group.

    • group

      public void group(@NonNull @NonNull String name, @NonNull @NonNull Runnable exec)
      Executes the given Runnable in a group.
      Parameters:
      name - the group name.
      exec - the Runnable to execute within the group.

    • group

      public <T> T group(@NonNull @NonNull String name, @NonNull @NonNull Callable<T> exec) throws Exception
      Executes the given callable in a group.
      Type Parameters:
      T - the object type returned by the given Callable.
      Parameters:
      name - the group name.
      exec - the Callable to execute within the group.
      Returns:
      the result returned by the Callable.
      Throws:
      Exception - propagate as-is the exception thrown by the Callable.

    • endGroup

      public void endGroup()
      Ends a group.

    • saveState

      public <T> void saveState(@NonNull @NonNull String name, @NonNull T value)
      Saves the state for current action, the state can only be retrieved by this action's post job execution.
      Type Parameters:
      T - the state value object type.
      Parameters:
      name - the state variable name.
      value - the state variable value.

    • getState

      public Optional<String> getState(@NonNull @NonNull String name)
      Gets the value of an state set by this action's main execution.
      Parameters:
      name - the state variable name.
      Returns:
      the state value or empty if state is not set.

    • setSecret

      public <T> void setSecret(@NonNull T value)
      Registers a secret which will get masked from logs.
      Type Parameters:
      T - the secret value object type.
      Parameters:
      value - the secret value.

    • isDebug

      public boolean isDebug()
      Returns true if DEBUG mode is enabled in the runner, false otherwise.
      Returns:
      true if DEBUG mode is enabled in the runner, false otherwise.

    • debug

      public void debug(@NonNull @NonNull String message)
      Prints a DEBUG message to user log.
      Parameters:
      message - the message.

    • notice

      public void notice(@NonNull @NonNull String message)
      Prints a NOTICE message to user log.
      Parameters:
      message - the message.

    • notice

      public void notice(@NonNull @NonNull String message, @NonNull @NonNull Optional<AnnotationProperties> properties)
      Prints a NOTICE message to user log.
      Parameters:
      message - the message.
      properties - the annotations to add to the message.

    • warning

      public void warning(@NonNull @NonNull String message)
      Prints a WARNING message to user log.
      Parameters:
      message - the message.

    • warning

      public void warning(@NonNull @NonNull String message, @NonNull @NonNull Optional<AnnotationProperties> properties)
      Prints a WARNING message to user log.
      Parameters:
      message - the message.
      properties - the annotations to add to the message.

    • error

      public void error(@NonNull @NonNull String message)
      Prints a ERROR message to user log.
      Parameters:
      message - the message.

    • error

      public void error(@NonNull @NonNull String message, @NonNull @NonNull Optional<AnnotationProperties> properties)
      Prints a ERROR message to user log with given annotation properties.
      Parameters:
      message - the message.
      properties - the annotations to add to the message.

    • fail

      public void fail(@NonNull @NonNull String message)
      Fails the process with the given message.
      Parameters:
      message - the error message.

    • getGitHubRepository

      public String getGitHubRepository()
      Returns the owner and repository name. For example, octocat/Hello-World. See GITHUB_REPOSITORY.
      Returns:
      the owner and repository name. For example, octocat/Hello-World. See GITHUB_REPOSITORY.
      Throws:
      NoSuchElementException - if the object does not exist.

    • getGitHubRefType

      public String getGitHubRefType()
      Returns the type of ref that triggered the workflow run. Valid values are branch or tag. See GITHUB_REF_TYPE.
      Returns:
      the type of ref that triggered the workflow run. Valid values are branch or tag. See GITHUB_REF_TYPE.
      Throws:
      NoSuchElementException - if the object does not exist.

    • isGitHubRefTypeBranch

      public boolean isGitHubRefTypeBranch()
      Returns true if the type of ref that triggered the workflow run is branch. See GITHUB_REF_TYPE.
      Returns:
      true if the type of ref that triggered the workflow run is branch. See GITHUB_REF_TYPE.
      Throws:
      NoSuchElementException - if the object does not exist.

    • isGitHubRefTypeTag

      public boolean isGitHubRefTypeTag()
      Returns true if the type of ref that triggered the workflow run is tag. See GITHUB_REF_TYPE.
      Returns:
      true if the type of ref that triggered the workflow run is tag. See GITHUB_REF_TYPE.
      Throws:
      NoSuchElementException - if the object does not exist.

    • getGitHubRef

      public String getGitHubRef()
      Returns the branch or tag ref that triggered the workflow run. See GITHUB_REF.
      Returns:
      the branch or tag ref that triggered the workflow run. See GITHUB_REF.
      Throws:
      NoSuchElementException - if the object does not exist.

    • getGitHubRefName

      public String getGitHubRefName()
      Returns the branch or tag name that triggered the workflow run. See GITHUB_REF_NAME.
      Returns:
      the branch or tag name that triggered the workflow run. See GITHUB_REF_NAME.
      Throws:
      NoSuchElementException - if the object does not exist.

    • getGitHubSha

      public String getGitHubSha()
      Returns the commit SHA that triggered the workflow. See GITHUB_SHA.
      Returns:
      the commit SHA that triggered the workflow. See GITHUB_SHA.
      Throws:
      NoSuchElementException - if the object does not exist.

    • getGitHubAbbreviatedSha

      public String getGitHubAbbreviatedSha()
      Returns the commit abbreviated SHA that triggered the workflow. See GITHUB_SHA.
      Returns:
      the commit abbreviated SHA that triggered the workflow. See GITHUB_SHA.
      Throws:
      NoSuchElementException - if the object does not exist.

    • getGitHubRunId

      public String getGitHubRunId()
      Returns the workflow run identifier. See GITHUB_RUN_ID.
      Returns:
      the workflow run identifier. See GITHUB_RUN_ID.
      Throws:
      NoSuchElementException - if the object does not exist.

    • getGitHubApiUrl

      public String getGitHubApiUrl()
      Returns the GitHub API url. See GITHUB_API_URL.
      Returns:
      the GitHub API url. See GITHUB_API_URL.
      Throws:
      NoSuchElementException - if the object does not exist.

    • getEnv

      public Optional<String> getEnv(@NonNull @NonNull String name)
      Gets the environment variable value.
      Parameters:
      name - the environment variable name.
      Returns:
      the value if the environment variable exists, or Optional.empty().

    • getRequiredEnv

      public String getRequiredEnv(@NonNull @NonNull String name)
      Gets an environment variable value.
      Parameters:
      name - the environment variable name.
      Returns:
      the value if the environment variable exists, or Optional.empty().