Building your Application

When an application is deployed from a GitHub repository, Porter will build your application by opening a PR that contains a GitHub Actions file in your repository.

​

Merging in the PR for GitHub Actions

When you create an application, you will be asked to merge in the PR that Porter has opened in your repository. Porter will open a PR that contains the GitHub Actions file from a new branch called porter-stack.

The GitHub actions file included in the PR will, by default, be triggered on any pushes to the specified git branch. Here’s an example file that could be written to your repository:

"on":
  push:
    branches:
    - master
name: Deploy to storm-king
jobs:
  porter-deploy:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout code
      uses: actions/checkout@v3
    - name: Set Github tag
      id: vars
      run: echo "sha_short=$(git rev-parse --short HEAD)" >> $GITHUB_OUTPUT
    - name: Setup porter
      uses: porter-dev/setup-porter@v0.1.0
    - name: Deploy stack
      timeout-minutes: 30
      run: porter apply -f ./porter.yaml
      env:
        PORTER_CLUSTER: "37"
        PORTER_HOST: https://dashboard.getporter.dev
        PORTER_PR_NUMBER: ${{ github.event.number }}
        PORTER_PROJECT: "18"
        PORTER_STACK_NAME: testasdfasdfasdf
        PORTER_TAG: ${{ steps.vars.outputs.sha_short }}
        PORTER_TOKEN: ${{ secrets.PORTER_STACK_18_37 }}

You can customize this GitHub action to be triggered on different actions than push. Please see the GitHub Actions docs for reference. As long as the steps Setup porter and Deploy stack are present in your github actions file, you can also prepend or append any steps as desired.

​

Viewing your Build Logs

You can view the build logs of your application from either the Porter dashboard or the GitHub Actions tab.

To view your build logs on GitHub, navigate to the Actions tab in your repository. Click on the most recent Deploy to Porter workflow to view the build logs of your application.

​

Retrying a Build on Failure

When builds fail, you can troubleshoot by viewing the logs from the Porter Dashboard or the Actions tab on GitHub. To retry a build, simply toggle the option to Re-run build and deploy on save, then click on Save Build Settings. This will re-trigger the github actions file present in your github repository.

You can also trigger a rerun of this GitHub Actions directly from GitHub by clicking on Re-run failed jobs button after selecting the job run.

​

Build-time Environment Variables

Many languages and frameworks require certain environment variables to be present during the build process. Any environment variable you add to an application on Porter will automatically be piped into your build process; there is no need for you to manually add these environment variables to the GitHub Actions file. Any supplementary environment variables you add to the GitHub Actions file will also be made available to your build process, however, as long as they are prefixed with PORTER_.

Please note that Secrets will not be made available to your build process. Learn more about Secrets here.

​

Using build-time environment variables for Dockerfile builds

If you are building your application via Dockerfile and require environment variables to be used during the build process, you can use the ARG keyword to make these variables available to your Dockerfile and the ${env-var-name} syntax to reference them elsewhere in the file. Example snippet from a Dockerfile:

...
ARG PORTER_ENV_VARIABLE
RUN echo "Here is my env variable: ${PORTER_ENV_VARIABLE}"
...

Note that if you are building via buildpacks, no additional configuration is required to make your build-time environment variables available to your build process.

​

Storing Container Images

When your application has built successfully, Porter will automatically push the resulting container images into a container registry in your connected cloud account and update your application with the new build.

​

Using Buildkit

For certain Dockerfile-based builds, Buildkit may be required to build successfully, such as when using COPY --chown. To enable buildkit, set the DOCKER_BUILDKIT environment variable to 1. This can be set at the Github Actions Workflow-level with the following snippet at the top-level of your Github Actions file:

# ... other parts of the workflow file go here
env:
  DOCKER_BUILDKIT: "1"