Skip to content

Commit 5e5345b

Browse files
jastangjastang
committed
Vale fixes.
Signed-off-by: Jason Tang <[email protected]>
1 parent 6e0fe86 commit 5e5345b

File tree

7 files changed

+203
-190
lines changed

7 files changed

+203
-190
lines changed

‎content/master/guides/extensions-release-process.md

Lines changed: 40 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -5,16 +5,16 @@ description: "Configuring build pipelines for Crossplane extensions with GitHub
55
Actions"
66
---
77

8-
Crossplane extensions are built as OCI images in the [xpkg] format. Authors and
9-
maintainers of Crossplane extensions must push their packages to an OCI
10-
registry before they can be used and referenced by Crossplane.
8+
Building a Crossplane extension involves creating OCI images in the [xpkg]
9+
format. Authors and maintainers of Crossplane extensions must push their
10+
packages to an OCI registry before Crossplane can reference and use them.
1111

1212
{{< hint "tip" >}}
13-
For more information about Crossplane packages, review the concepts
14-
[here]({{<ref "../concepts/packages" >}}).
13+
For more information about Crossplane packages, review the
14+
[xpkg concepts]({{<ref "../../master/concepts/packages" >}}).
1515
{{< /hint >}}
1616

17-
## Typical Workflow
17+
## Typical workflow
1818

1919
This guide covers configuring a GitHub Action for building Crossplane
2020
providers and functions and pushing them to an OCI registry such as `ghcr.io`.
@@ -27,22 +27,22 @@ A typical GitHub workflow definition contains the following steps:
2727
4. Pushing (publishing) the artifact
2828

2929
{{< hint "warning" >}}
30-
The supplied credentials for the remote registry require read+write access, as
31-
subsequent requests to the registry will specify `push` authorization scope.
30+
The supplied credentials for the remote registry require read and write access
31+
as upload requests to the registry specify `push` authorization scope.
3232
{{< /hint >}}
3333

34-
Fortunately, the template repositories for [providers] and [functions] provide
34+
The template GitHub repositories for [providers] and [functions] provide
3535
a functional GitHub Action in `.github/workflows/ci.yml`. The following
3636
sections of this guide cover configuration options and conventions for each.
3737

3838
## Common Configuration
3939

4040
All workflows require references to credentials for a remote registry.
41-
Typically, these are stored as [GitHub Actions Secrets], and authentication
42-
is performed via the`docker/login-action`
41+
Typically, users configure them as [GitHub Actions Secrets], and the workflow
42+
performs authentication via the`docker/login-action`
4343
[action](http://github.com/docker/login-action).
4444

45-
For example, adding the following step to a pipeline will authenticate
45+
For example, adding the following step to a pipeline authenticates
4646
the job to `ghcr.io` using the workflow's ephemeral GitHub OIDC token.
4747

4848
```yaml
@@ -55,12 +55,14 @@ the job to `ghcr.io` using the workflow's ephemeral GitHub OIDC token.
5555
```
5656
5757
{{< hint "important" >}}
58-
By default, the job's OIDC token will not have permission to write packages
59-
to `ghcr.io`. This can be configured in the GitHub repository's settings, or
60-
declared [explicitly](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/controlling-permissions-for-github_token) in the workflow definition YAML file.
58+
By default, the job's OIDC token don't have permission to write packages
59+
to `ghcr.io`. Permissions are configurable in the GitHub repository's settings
60+
or declared
61+
[explicitly](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/controlling-permissions-for-github_token)
62+
in the workflow definition YAML file.
6163
{{< /hint >}}
6264

63-
For other registries, it is still best practice to reference credentials as
65+
For other registries, it's still best practice to reference credentials as
6466
custom Secret variables. For example:
6567

6668
```yaml
@@ -73,10 +75,10 @@ custom Secret variables. For example:
7375
password: ${{ secrets.XPKG_TOKEN }}
7476
```
7577

76-
## Branching Conventions
78+
## Branching conventions
7779

7880
Repositories for Crossplane extensions follow similar branching conventions
79-
to upstream Crossplane, where the release process is predicated on the workflow
81+
to upstream Crossplane, where the release process assumes the workflow
8082
executing in branches with the `release-*` prefix. `main` is often included,
8183
though a conventional release process would not build and push off of tags on
8284
`main`.
@@ -91,18 +93,18 @@ on:
9193

9294
For example, when releasing `v0.1.0` of an extension, the conventional
9395
process is to cut a release branch `release-0.1` at the git commit
94-
where it will be built, and tag it as `v0.1.0`.
96+
where it builds from, and tag it as `v0.1.0`.
9597

9698
{{< hint "note" >}}
9799
Some custom workflows may accept an explicit input for the remote reference,
98-
which overrides inferring from a git ref or tag. The [ci.yml] file for
100+
which overrides inferring from a git ref or tag. The [`ci.yml`] file for
99101
`crossplane-contrib/function-python` is a good example.
100102
{{< /hint >}}
101103

102-
## Configuring Workflows for Functions
104+
## Configuring workflows for function packages
103105

104-
Function workflow definitions will differ based on the base language the
105-
function is implemented in. For example, a Python function will require
106+
Function workflow definitions differ based on the base language the
107+
function implementation uses. For example, a Python function requires
106108
a Python environment in the GitHub Action runner:
107109

108110
```yaml
@@ -121,9 +123,9 @@ a Python environment in the GitHub Action runner:
121123
While the template repository provides a working pipeline definition, users may
122124
choose to customize their environment with different tooling.
123125

124-
Functions also require a runtime image of the core business logic to be
125-
built and embedded into the Function package. The default workflow definition
126-
will build for two platforms: `linux/amd64` and `linux/arm64`.
126+
Functions also require a runtime image of the core business logic to
127+
build and embed into the Function package. The default workflow definition
128+
builds for two platforms: `linux/amd64` and `linux/arm64`.
127129

128130
```yaml
129131
- name: Build Runtime
@@ -140,7 +142,7 @@ will build for two platforms: `linux/amd64` and `linux/arm64`.
140142
outputs: type=docker,dest=runtime-${{ matrix.arch }}.tar
141143
```
142144

143-
## Configuring Workflows for Providers
145+
## Configuring workflows for provider packages
144146

145147
Providers, unlike Functions, use custom `make` targets in the [build submodule]
146148
for building and pushing Crossplane Provider packages.
@@ -151,13 +153,13 @@ Configuring the workflow for a specific registry involves two steps:
151153
2. Referencing GitHub Actions Secrets for authorized credentials to the
152154
registry.
153155

154-
### Configure Target Registry
156+
### Configure target registry
155157

156158
The provider template repository includes a top-level `Makefile`. Edit
157159
the following variables to define the target registry:
158160

159161
1. `XPKG_REG_ORGS` - a space-delimited list of target repositories.
160-
2. `XPKG_REG_ORGS_NO_PROMOTE` - for registries that do not use or infer
162+
2. `XPKG_REG_ORGS_NO_PROMOTE` - for registries that don't use or infer
161163
channel tags, such as `xpkg.upbound.io`.
162164

163165
For example, the following dual-pushes to `xpkg.upbound.io` as well as
@@ -169,10 +171,10 @@ XPKG_REG_ORGS ?= xpkg.upbound.io/crossplane-contrib index.docker.io/crossplaneco
169171
XPKG_REG_ORGS_NO_PROMOTE ?= xpkg.upbound.io/crossplane-contrib
170172
```
171173

172-
## Reusable Workflows
174+
## Reusable workflows
173175

174176
The [crossplane-contrib/provider-workflows] repository provide reusable
175-
workflow definitions that can be called from a custom CI pipeline.
177+
workflow definitions that are callable from a custom CI pipeline.
176178

177179
For example, the following snippet references the callable workflow to
178180
build and push the `provider-kubernetes` package to both `ghcr.io` and
@@ -193,22 +195,22 @@ jobs:
193195
```
194196

195197
{{< hint "tip" >}}
196-
The reusable workflows referenced here will publish to `ghcr.io` by default.
197-
Ensure that the default GitHub Actions OIDC token is granted the
198+
The reusable workflows referenced here publish to `ghcr.io` by default.
199+
Ensure that the default GitHub Actions OIDC token inherits the
198200
`packages: write` permission.
199201
{{< /hint >}}
200202

201203
## Troubleshooting
202204

203205
{{< expand "Why is my workflow is failing with a 404 error code?" >}}
204-
Ensure the target repository exists in the registry. You will need to create
205-
it if it does not already exist.
206+
Ensure the target repository exists in the registry. You need to create
207+
it if it doesn't already exist.
206208
{{</expand >}}
207209

208210
{{< expand "Why is my workflow failing with a 401 error code?" >}}
209-
Ensure the credentials used during the registry login step are authorized to
211+
Ensure the credentials used during the registry login step has authorization to
210212
pull and push, and that the `{{ secrets.* }}` variable substitutions match
211-
what is configured in GitHub.
213+
what's configured in GitHub.
212214
{{</expand >}}
213215

214216
<!-- Named Links -->
@@ -217,5 +219,5 @@ what is configured in GitHub.
217219
[providers]: https://github.com/crossplane/upjet-provider-template/blob/main/.github/workflows/ci.yml
218220
[GitHub Actions Secrets]: https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions
219221
[build submodule]: https://github.com/crossplane/build
220-
[ci.yml]: https://github.com/crossplane-contrib/function-python/blob/main/.github/workflows/ci.yml
222+
[`ci.yml`]: https://github.com/crossplane-contrib/function-python/blob/main/.github/workflows/ci.yml
221223
[crossplane-contrib/provider-workflows]: https://github.com/crossplane-contrib/provider-workflows/blob/main/.github/workflows

‎content/v1.17/guides/extensions-release-process.md

Lines changed: 40 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -5,16 +5,16 @@ description: "Configuring build pipelines for Crossplane extensions with GitHub
55
Actions"
66
---
77

8-
Crossplane extensions are built as OCI images in the [xpkg] format. Authors and
9-
maintainers of Crossplane extensions must push their packages to an OCI
10-
registry before they can be used and referenced by Crossplane.
8+
Building a Crossplane extension involves creating OCI images in the [xpkg]
9+
format. Authors and maintainers of Crossplane extensions must push their
10+
packages to an OCI registry before Crossplane can reference and use them.
1111

1212
{{< hint "tip" >}}
13-
For more information about Crossplane packages, review the concepts
14-
[here]({{<ref "../concepts/packages" >}}).
13+
For more information about Crossplane packages, review the
14+
[xpkg concepts]({{<ref "../../master/concepts/packages" >}}).
1515
{{< /hint >}}
1616

17-
## Typical Workflow
17+
## Typical workflow
1818

1919
This guide covers configuring a GitHub Action for building Crossplane
2020
providers and functions and pushing them to an OCI registry such as `ghcr.io`.
@@ -27,22 +27,22 @@ A typical GitHub workflow definition contains the following steps:
2727
4. Pushing (publishing) the artifact
2828

2929
{{< hint "warning" >}}
30-
The supplied credentials for the remote registry require read+write access, as
31-
subsequent requests to the registry will specify `push` authorization scope.
30+
The supplied credentials for the remote registry require read and write access
31+
as upload requests to the registry specify `push` authorization scope.
3232
{{< /hint >}}
3333

34-
Fortunately, the template repositories for [providers] and [functions] provide
34+
The template GitHub repositories for [providers] and [functions] provide
3535
a functional GitHub Action in `.github/workflows/ci.yml`. The following
3636
sections of this guide cover configuration options and conventions for each.
3737

3838
## Common Configuration
3939

4040
All workflows require references to credentials for a remote registry.
41-
Typically, these are stored as [GitHub Actions Secrets], and authentication
42-
is performed via the`docker/login-action`
41+
Typically, users configure them as [GitHub Actions Secrets], and the workflow
42+
performs authentication via the`docker/login-action`
4343
[action](http://github.com/docker/login-action).
4444

45-
For example, adding the following step to a pipeline will authenticate
45+
For example, adding the following step to a pipeline authenticates
4646
the job to `ghcr.io` using the workflow's ephemeral GitHub OIDC token.
4747

4848
```yaml
@@ -55,12 +55,14 @@ the job to `ghcr.io` using the workflow's ephemeral GitHub OIDC token.
5555
```
5656
5757
{{< hint "important" >}}
58-
By default, the job's OIDC token will not have permission to write packages
59-
to `ghcr.io`. This can be configured in the GitHub repository's settings, or
60-
declared [explicitly](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/controlling-permissions-for-github_token) in the workflow definition YAML file.
58+
By default, the job's OIDC token don't have permission to write packages
59+
to `ghcr.io`. Permissions are configurable in the GitHub repository's settings
60+
or declared
61+
[explicitly](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/controlling-permissions-for-github_token)
62+
in the workflow definition YAML file.
6163
{{< /hint >}}
6264

63-
For other registries, it is still best practice to reference credentials as
65+
For other registries, it's still best practice to reference credentials as
6466
custom Secret variables. For example:
6567

6668
```yaml
@@ -73,10 +75,10 @@ custom Secret variables. For example:
7375
password: ${{ secrets.XPKG_TOKEN }}
7476
```
7577

76-
## Branching Conventions
78+
## Branching conventions
7779

7880
Repositories for Crossplane extensions follow similar branching conventions
79-
to upstream Crossplane, where the release process is predicated on the workflow
81+
to upstream Crossplane, where the release process assumes the workflow
8082
executing in branches with the `release-*` prefix. `main` is often included,
8183
though a conventional release process would not build and push off of tags on
8284
`main`.
@@ -91,18 +93,18 @@ on:
9193

9294
For example, when releasing `v0.1.0` of an extension, the conventional
9395
process is to cut a release branch `release-0.1` at the git commit
94-
where it will be built, and tag it as `v0.1.0`.
96+
where it builds from, and tag it as `v0.1.0`.
9597

9698
{{< hint "note" >}}
9799
Some custom workflows may accept an explicit input for the remote reference,
98-
which overrides inferring from a git ref or tag. The [ci.yml] file for
100+
which overrides inferring from a git ref or tag. The [`ci.yml`] file for
99101
`crossplane-contrib/function-python` is a good example.
100102
{{< /hint >}}
101103

102-
## Configuring Workflows for Functions
104+
## Configuring workflows for function packages
103105

104-
Function workflow definitions will differ based on the base language the
105-
function is implemented in. For example, a Python function will require
106+
Function workflow definitions differ based on the base language the
107+
function implementation uses. For example, a Python function requires
106108
a Python environment in the GitHub Action runner:
107109

108110
```yaml
@@ -121,9 +123,9 @@ a Python environment in the GitHub Action runner:
121123
While the template repository provides a working pipeline definition, users may
122124
choose to customize their environment with different tooling.
123125

124-
Functions also require a runtime image of the core business logic to be
125-
built and embedded into the Function package. The default workflow definition
126-
will build for two platforms: `linux/amd64` and `linux/arm64`.
126+
Functions also require a runtime image of the core business logic to
127+
build and embed into the Function package. The default workflow definition
128+
builds for two platforms: `linux/amd64` and `linux/arm64`.
127129

128130
```yaml
129131
- name: Build Runtime
@@ -140,7 +142,7 @@ will build for two platforms: `linux/amd64` and `linux/arm64`.
140142
outputs: type=docker,dest=runtime-${{ matrix.arch }}.tar
141143
```
142144

143-
## Configuring Workflows for Providers
145+
## Configuring workflows for provider packages
144146

145147
Providers, unlike Functions, use custom `make` targets in the [build submodule]
146148
for building and pushing Crossplane Provider packages.
@@ -151,13 +153,13 @@ Configuring the workflow for a specific registry involves two steps:
151153
2. Referencing GitHub Actions Secrets for authorized credentials to the
152154
registry.
153155

154-
### Configure Target Registry
156+
### Configure target registry
155157

156158
The provider template repository includes a top-level `Makefile`. Edit
157159
the following variables to define the target registry:
158160

159161
1. `XPKG_REG_ORGS` - a space-delimited list of target repositories.
160-
2. `XPKG_REG_ORGS_NO_PROMOTE` - for registries that do not use or infer
162+
2. `XPKG_REG_ORGS_NO_PROMOTE` - for registries that don't use or infer
161163
channel tags, such as `xpkg.upbound.io`.
162164

163165
For example, the following dual-pushes to `xpkg.upbound.io` as well as
@@ -169,10 +171,10 @@ XPKG_REG_ORGS ?= xpkg.upbound.io/crossplane-contrib index.docker.io/crossplaneco
169171
XPKG_REG_ORGS_NO_PROMOTE ?= xpkg.upbound.io/crossplane-contrib
170172
```
171173

172-
## Reusable Workflows
174+
## Reusable workflows
173175

174176
The [crossplane-contrib/provider-workflows] repository provide reusable
175-
workflow definitions that can be called from a custom CI pipeline.
177+
workflow definitions that are callable from a custom CI pipeline.
176178

177179
For example, the following snippet references the callable workflow to
178180
build and push the `provider-kubernetes` package to both `ghcr.io` and
@@ -193,22 +195,22 @@ jobs:
193195
```
194196

195197
{{< hint "tip" >}}
196-
The reusable workflows referenced here will publish to `ghcr.io` by default.
197-
Ensure that the default GitHub Actions OIDC token is granted the
198+
The reusable workflows referenced here publish to `ghcr.io` by default.
199+
Ensure that the default GitHub Actions OIDC token inherits the
198200
`packages: write` permission.
199201
{{< /hint >}}
200202

201203
## Troubleshooting
202204

203205
{{< expand "Why is my workflow is failing with a 404 error code?" >}}
204-
Ensure the target repository exists in the registry. You will need to create
205-
it if it does not already exist.
206+
Ensure the target repository exists in the registry. You need to create
207+
it if it doesn't already exist.
206208
{{</expand >}}
207209

208210
{{< expand "Why is my workflow failing with a 401 error code?" >}}
209-
Ensure the credentials used during the registry login step are authorized to
211+
Ensure the credentials used during the registry login step has authorization to
210212
pull and push, and that the `{{ secrets.* }}` variable substitutions match
211-
what is configured in GitHub.
213+
what's configured in GitHub.
212214
{{</expand >}}
213215

214216
<!-- Named Links -->
@@ -217,5 +219,5 @@ what is configured in GitHub.
217219
[providers]: https://github.com/crossplane/upjet-provider-template/blob/main/.github/workflows/ci.yml
218220
[GitHub Actions Secrets]: https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions
219221
[build submodule]: https://github.com/crossplane/build
220-
[ci.yml]: https://github.com/crossplane-contrib/function-python/blob/main/.github/workflows/ci.yml
222+
[`ci.yml`]: https://github.com/crossplane-contrib/function-python/blob/main/.github/workflows/ci.yml
221223
[crossplane-contrib/provider-workflows]: https://github.com/crossplane-contrib/provider-workflows/blob/main/.github/workflows

0 commit comments

Comments
 (0)